From f33512bbf1ef4c752a17764da5795813b4cc2ee8 Mon Sep 17 00:00:00 2001 From: Raymond Toy Date: Thu, 16 Mar 2023 07:52:05 -0700 Subject: [PATCH 1/2] Address #47: Add xrefs to X3J13 issues. Add a macro, `@X3J13` to produce a link to the corresponding issue in the spec. Update all uses of the X3J13 issues to use the macro. --- docs/cmu-user/cmu-user.texi | 7 ++++++ docs/cmu-user/compiler-hint.texi | 4 +-- docs/cmu-user/compiler.texi | 42 ++++++++++++++++---------------- 3 files changed, 30 insertions(+), 23 deletions(-) diff --git a/docs/cmu-user/cmu-user.texi b/docs/cmu-user/cmu-user.texi index 05de360..ee5d5e3 100644 --- a/docs/cmu-user/cmu-user.texi +++ b/docs/cmu-user/cmu-user.texi @@ -146,6 +146,13 @@ Alien @code{\arg\} @end macro +@c Link to CLHS issues. The link only needs to be the last part of +@c the file; we prepend the appropriate CLHS path. The text describes +@c the issue---usually the name of the issue. +@macro X3J13 {text, link} +X3J13 cleanup ``@url{https://www.lispworks.com/documentation/HyperSpec/Issues/\link\,\text\}'' +@end macro + @macro manualdate {} December 2018 @end macro diff --git a/docs/cmu-user/compiler-hint.texi b/docs/cmu-user/compiler-hint.texi index b1df13b..5af6c29 100644 --- a/docs/cmu-user/compiler-hint.texi +++ b/docs/cmu-user/compiler-hint.texi @@ -521,8 +521,8 @@ return, then (in safe compilation policies) a ``@code{NIL Function @end itemize This is consistent with the new interpretation of function types and -the @code{ftype} declaration in the proposed X3J13 -``function-type-argument-type-semantics'' cleanup. Note also, that if +the @code{ftype} declaration in the proposed @X3J13{ +function-type-argument-type-semantics, iss176_w.htm}. Note also, that if you don't explicitly declare the type of a function using a global @code{ftype} declaration, then @python{} will compute a function type from the definition, providing a degree of inter-routine type diff --git a/docs/cmu-user/compiler.texi b/docs/cmu-user/compiler.texi index c7abda6..27ed0bc 100644 --- a/docs/cmu-user/compiler.texi +++ b/docs/cmu-user/compiler.texi @@ -59,18 +59,18 @@ Functions may be compiled using @code{compile}, @code{compile-file}, or @var{name} is @false, the compiled function object is returned. If @var{definition} is supplied, it should be a lambda expression that is to be compiled and then placed in the function cell of - @var{name}. As per the proposed X3J13 cleanup - ``compile-argument-problems'', @var{definition} may also be an + @var{name}. As per the proposed @X3J13{ + compile-argument-problems, iss058_w.htm}, @var{definition} may also be an interpreted function. - The return values are as per the proposed X3J13 cleanup - ``compiler-diagnostics''. The first value is the function name or - function object. The second value is @false{} if no compiler - diagnostics were issued, and @true{} otherwise. The third value is - @false{} if no compiler diagnostics other than style warnings were - issued. A non-@false{} value indicates that there were ``serious'' - compiler diagnostics issued, or that other conditions of type - @tindexed{error} or @tindexed{warning} (but not + The return values are as per the proposed + @X3J13{compiler-diagnostics, iss065_w.htm}. The first value is the + function name or function object. The second value is @false{} if + no compiler diagnostics were issued, and @true{} otherwise. The + third value is @false{} if no compiler diagnostics other than style + warnings were issued. A non-@false{} value indicates that there + were ``serious'' compiler diagnostics issued, or that other + conditions of type @tindexed{error} or @tindexed{warning} (but not @tindexed{style-warning}) were signaled during compilation. @end defun @@ -161,8 +161,8 @@ If non-@nil, enable recording of cross-reference and loading the fasl later will populate the cross-reference database. @end table - The return values are as per the proposed X3J13 cleanup - ``compiler-diagnostics''. The first value from @code{compile-file} + The return values are as per the proposed @X3J13{ + compiler-diagnostics, iss065_w.htm}. The first value from @code{compile-file} is the truename of the output file, or @false{} if the file could not be created. The interpretation of the second and third values is described above for @code{compile}. @@ -192,8 +192,8 @@ If non-@nil, enable recording of cross-reference @cpindex compilation @subentry units @cmucl{} supports the @code{with-compilation-unit} macro added to the -language by the X3J13 ``with-compilation-unit'' compiler cleanup -issue. This provides a mechanism for eliminating spurious undefined +language by the @X3J13{with-compilation-unit, iss360_w.htm}. +This provides a mechanism for eliminating spurious undefined warnings when there are forward references across files, and also provides a standard way to access compiler extensions. @@ -595,12 +595,12 @@ Notes are used when there is something that seems a bit odd, but that might reasonably appear in correct programs. @end table -Note that the compiler does not fully conform to the proposed X3J13 -``compiler-diagnostics'' cleanup. Errors, warnings and notes mostly -correspond to errors, warnings and style-warnings, but many things -that the cleanup considers to be style-warnings are printed as -warnings rather than notes. Also, warnings, style-warnings and most -errors aren't really signaled using the condition system. +Note that the compiler does not fully conform to the proposed +@X3J13{compiler-diagnostics, iss065_w.htm}. Errors, warnings and +notes mostly correspond to errors, warnings and style-warnings, but +many things that the cleanup considers to be style-warnings are +printed as warnings rather than notes. Also, warnings, style-warnings +and most errors aren't really signaled using the condition system. @node Errors During Macroexpansion @@ -1273,7 +1273,7 @@ See also the @kwd{context-declarations} option to @cindex static functions Since @clisp{} forbids the redefinition of standard functions@footnote{See the -proposed X3J13 ``lisp-symbol-redefinition'' cleanup.}, the compiler can have +proposed @X3J13{lisp-symbol-redefinition, iss214_w.htm}.}, the compiler can have special knowledge of these standard functions embedded in it. This special knowledge is used in various ways (open coding, inline expansion, source transformation), but the implications to the user are basically the same: -- GitLab From 3a34114635c3a003d7add8875cb0bc79d98635e4 Mon Sep 17 00:00:00 2001 From: Raymond Toy Date: Thu, 16 Mar 2023 08:07:41 -0700 Subject: [PATCH 2/2] Rename @X3J13 to @clhscleanup Macro names need use just letters to work consistently with TeX (per TexInfo manual). Hence rename X3J13 to clhscleanup. --- docs/cmu-user/cmu-user.texi | 2 +- docs/cmu-user/compiler-hint.texi | 2 +- docs/cmu-user/compiler.texi | 12 ++++++------ 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/cmu-user/cmu-user.texi b/docs/cmu-user/cmu-user.texi index d06957a..9c9d9b8 100644 --- a/docs/cmu-user/cmu-user.texi +++ b/docs/cmu-user/cmu-user.texi @@ -154,7 +154,7 @@ Alien @c Link to CLHS issues. The link only needs to be the last part of @c the file; we prepend the appropriate CLHS path. The text describes @c the issue---usually the name of the issue. -@macro X3J13 {text, link} +@macro clhscleanup {text, link} X3J13 cleanup ``@url{https://www.lispworks.com/documentation/HyperSpec/Issues/\link\,\text\}'' @end macro diff --git a/docs/cmu-user/compiler-hint.texi b/docs/cmu-user/compiler-hint.texi index 366f227..7b5ac53 100644 --- a/docs/cmu-user/compiler-hint.texi +++ b/docs/cmu-user/compiler-hint.texi @@ -521,7 +521,7 @@ return, then (in safe compilation policies) a ``@code{NIL Function @end itemize This is consistent with the new interpretation of function types and -the @code{ftype} declaration in the proposed @X3J13{ +the @code{ftype} declaration in the proposed @clhscleanup{ function-type-argument-type-semantics, iss176_w.htm}. Note also, that if you don't explicitly declare the type of a function using a global @code{ftype} declaration, then @python{} will compute a function type diff --git a/docs/cmu-user/compiler.texi b/docs/cmu-user/compiler.texi index b71de27..49f72f8 100644 --- a/docs/cmu-user/compiler.texi +++ b/docs/cmu-user/compiler.texi @@ -59,12 +59,12 @@ Functions may be compiled using @code{compile}, @code{compile-file}, or @var{name} is @false, the compiled function object is returned. If @var{definition} is supplied, it should be a lambda expression that is to be compiled and then placed in the function cell of - @var{name}. As per the proposed @X3J13{ + @var{name}. As per the proposed @clhscleanup{ compile-argument-problems, iss058_w.htm}, @var{definition} may also be an interpreted function. The return values are as per the proposed - @X3J13{compiler-diagnostics, iss065_w.htm}. The first value is the + @clhscleanup{compiler-diagnostics, iss065_w.htm}. The first value is the function name or function object. The second value is @false{} if no compiler diagnostics were issued, and @true{} otherwise. The third value is @false{} if no compiler diagnostics other than style @@ -161,7 +161,7 @@ If non-@nil, enable recording of cross-reference and loading the fasl later will populate the cross-reference database. @end table - The return values are as per the proposed @X3J13{ + The return values are as per the proposed @clhscleanup{ compiler-diagnostics, iss065_w.htm}. The first value from @code{compile-file} is the truename of the output file, or @false{} if the file could not be created. The interpretation of the second and third values @@ -192,7 +192,7 @@ If non-@nil, enable recording of cross-reference @cpindex compilation @subentry units @cmucl{} supports the @macref{with-compilation-unit} macro added to the -language by the @X3J13{with-compilation-unit, iss360_w.htm}. +language by the @clhscleanup{with-compilation-unit, iss360_w.htm}. This provides a mechanism for eliminating spurious undefined warnings when there are forward references across files, and also provides a standard way to access compiler extensions. @@ -597,7 +597,7 @@ Notes are used when there is something that seems a bit @end table Note that the compiler does not fully conform to the proposed -@X3J13{compiler-diagnostics, iss065_w.htm}. Errors, warnings and +@clhscleanup{compiler-diagnostics, iss065_w.htm}. Errors, warnings and notes mostly correspond to errors, warnings and style-warnings, but many things that the cleanup considers to be style-warnings are printed as warnings rather than notes. Also, warnings, style-warnings @@ -1275,7 +1275,7 @@ option to @macref{with-compilation-unit}. @cindex static functions Since @clisp{} forbids the redefinition of standard functions@footnote{See the -proposed @X3J13{lisp-symbol-redefinition, iss214_w.htm}.}, the compiler can have +proposed @clhscleanup{lisp-symbol-redefinition, iss214_w.htm}.}, the compiler can have special knowledge of these standard functions embedded in it. This special knowledge is used in various ways (open coding, inline expansion, source transformation), but the implications to the user are basically the same: -- GitLab