From patchwork Tue May 30 07:20:51 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Marc_Poulhi=C3=A8s?= X-Patchwork-Id: 70281 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 260773848372 for ; Tue, 30 May 2023 07:23:13 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 260773848372 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1685431393; bh=mfvLN3KkuGFVtR2/tlYMJuAMkn5e6Ia61dulK/vOOio=; h=To:Cc:Subject:Date:List-Id:List-Unsubscribe:List-Archive: List-Post:List-Help:List-Subscribe:From:Reply-To:From; b=vEwFV6rC8g3D0HxSOYJL1J+BEVSmniey6gV7WfsUkuygfEgpg5Qx/XMT8UiAgM68a O9vJUTyU9ZMMIacaY6NPWnPLzNE2aahKi5kArM3KITvbzrx3I49mZwwrVsNNmViWDJ w/ZGfa+KHXsT/KbOM6+f3JZeCGRiGi6McTKh8aaA= X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from mail-wm1-x333.google.com (mail-wm1-x333.google.com [IPv6:2a00:1450:4864:20::333]) by sourceware.org (Postfix) with ESMTPS id E0A6F385C6DE for ; Tue, 30 May 2023 07:20:53 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org E0A6F385C6DE Received: by mail-wm1-x333.google.com with SMTP id 5b1f17b1804b1-3f68fc6b479so42074225e9.2 for ; Tue, 30 May 2023 00:20:53 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1685431252; x=1688023252; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=mfvLN3KkuGFVtR2/tlYMJuAMkn5e6Ia61dulK/vOOio=; b=YeWrwipgJ2O80VKXoOe78veT887rMZjzhOh0Dpp+SQREr/nqdI03dS/jlKskLRT/pS 9Idc47yNeQUw9537OTrUd1+Elu6yqZJO19GwSflXfq7RQdzTemITEbhj9wk0AlUV4Lnv RfilgX+7RzF5jF/Ay3umhafCJsCUpatMJ5efBRhJB6U2DPZo60ZkWprLoKBPj/FzMMGk 22oQPIJKNMejrPzlqyyYkszrJJksAKouMtzUxeRLq7MRBnb4qq5tpx5QafWNcnbmOB5Z 6E3H1tyDzECQNR7Zw+GlfqGDIgOilJYatMjbe9rfZPZIOG//shRrTu8WdzVJn6lkzN8j +v9Q== X-Gm-Message-State: AC+VfDzXxBpBtfkxwrWm0n5/+NoRbDAwXmJvZnSLmlX315FTzmCIAjSO cSPe87AX6fmPpm4M9ZkoSn/aKiUVDsOW9ctX4emPig== X-Google-Smtp-Source: ACHHUZ6c3z9dkiPBSaeOAafvjeXvsw+1CoDItMviQPx+di6DiGO4bVf4dbr/4V7Vd+d8PB03Msdtrg== X-Received: by 2002:a7b:c8ce:0:b0:3f6:444:b33e with SMTP id f14-20020a7bc8ce000000b003f60444b33emr803495wml.30.1685431252653; Tue, 30 May 2023 00:20:52 -0700 (PDT) Received: from localhost.localdomain ([2001:861:3382:1a90:7733:a608:a415:6b2a]) by smtp.gmail.com with ESMTPSA id t7-20020a7bc3c7000000b003f6132f95e6sm19982670wmj.35.2023.05.30.00.20.51 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 30 May 2023 00:20:52 -0700 (PDT) To: gcc-patches@gcc.gnu.org Cc: Ronan Desplanques Subject: [COMMITTED] ada: Fix minor issues in user's guide Date: Tue, 30 May 2023 09:20:51 +0200 Message-Id: <20230530072051.2499815-1-poulhies@adacore.com> X-Mailer: git-send-email 2.40.0 MIME-Version: 1.0 X-Spam-Status: No, score=-13.7 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_PASS, TXREP, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: =?utf-8?q?Marc_Poulhi=C3=A8s_via_Gcc-patches?= From: =?utf-8?q?Marc_Poulhi=C3=A8s?= Reply-To: =?utf-8?q?Marc_Poulhi=C3=A8s?= Errors-To: gcc-patches-bounces+patchwork=sourceware.org@gcc.gnu.org Sender: "Gcc-patches" From: Ronan Desplanques gcc/ada/ * doc/gnat_ugn/building_executable_programs_with_gnat.rst: Fix minor issues. * doc/gnat_ugn/the_gnat_compilation_model.rst: Fix minor issues. * gnat_ugn.texi: Regenerate. Tested on x86_64-pc-linux-gnu, committed on master. --- ...building_executable_programs_with_gnat.rst | 32 ++++++++--------- .../gnat_ugn/the_gnat_compilation_model.rst | 2 +- gcc/ada/gnat_ugn.texi | 34 +++++++++---------- 3 files changed, 32 insertions(+), 36 deletions(-) diff --git a/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst b/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst index 2838a302f2e..20e003d4ac7 100644 --- a/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst +++ b/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst @@ -895,12 +895,12 @@ by ``gnatmake``. It may be necessary to use the switch Examples of ``gnatmake`` Usage ------------------------------ -*gnatmake hello.adb* +``gnatmake hello.adb`` Compile all files necessary to bind and link the main program :file:`hello.adb` (containing unit ``Hello``) and bind and link the resulting object files to generate an executable file :file:`hello`. -*gnatmake main1 main2 main3* +``gnatmake main1 main2 main3`` Compile all files necessary to bind and link the main programs :file:`main1.adb` (containing unit ``Main1``), :file:`main2.adb` (containing unit ``Main2``) and :file:`main3.adb` @@ -908,7 +908,7 @@ Examples of ``gnatmake`` Usage to generate three executable files :file:`main1`, :file:`main2` and :file:`main3`. -*gnatmake -q Main_Unit -cargs -O2 -bargs -l* +``gnatmake -q Main_Unit -cargs -O2 -bargs -l`` Compile all files necessary to bind and link the main program unit ``Main_Unit`` (from file :file:`main_unit.adb`). All compilations will be done with optimization level 2 and the order of elaboration will be @@ -949,7 +949,7 @@ You need *not* compile the following files * subunits -because they are compiled as part of compiling related units. GNAT +because they are compiled as part of compiling related units. GNAT compiles package specs when the corresponding body is compiled, and subunits when the parent is compiled. @@ -997,8 +997,6 @@ two output files in the current directory, but you may specify a source file in any directory using an absolute or relative path specification containing the directory information. -TESTING: the :switch:`--foobar{NN}` switch - .. index:: gnat1 ``gcc`` is actually a driver program that looks at the extensions of @@ -1068,7 +1066,7 @@ directories, in the following order: * The content of the :file:`ada_source_path` file which is part of the GNAT installation tree and is used to store standard libraries such as the GNAT Run Time Library (RTL) source files. - :ref:`Installing_a_library` + See also :ref:`Installing_a_library`. Specifying the switch :switch:`-I-` inhibits the use of the directory @@ -1159,7 +1157,7 @@ Compile body in file :file:`xyz.adb` with all default options. $ gcc -c -O2 -gnata xyz-def.adb Compile the child unit package in file :file:`xyz-def.adb` with extensive -optimizations, and pragma ``Assert``/`Debug` statements +optimizations, and pragma ``Assert``/``Debug`` statements enabled. .. code-block:: sh @@ -1274,7 +1272,7 @@ Alphabetical List of All Switches size of the executable, compared with a traditional per-unit compilation with inlining across units enabled by the :switch:`-gnatn` switch. The drawback of this approach is that it may require more memory and that - the debugging information generated by -g with it might be hardly usable. + the debugging information generated by ``-g`` with it might be hardly usable. The switch, as well as the accompanying :switch:`-Ox` switches, must be specified both for the compilation and the link phases. If the ``n`` parameter is specified, the optimization and final code @@ -1472,7 +1470,7 @@ Alphabetical List of All Switches This switch will generate an intermediate representation suitable for use by CodePeer (:file:`.scil` files). This switch is not compatible with code generation (it will, among other things, disable some switches such - as -gnatn, and enable others such as -gnata). + as ``-gnatn``, and enable others such as ``-gnata``). .. index:: -gnatd (gcc) @@ -1482,9 +1480,9 @@ Alphabetical List of All Switches the :switch:`-gnatd` specifies the specific debug options. The possible characters are 0-9, a-z, A-Z, optionally preceded by a dot or underscore. See compiler source file :file:`debug.adb` for details of the implemented - debug options. Certain debug options are relevant to applications + debug options. Certain debug options are relevant to application programmers, and these are documented at appropriate points in this - users guide. + user's guide. .. index:: -gnatD[nn] (gcc) @@ -1493,7 +1491,7 @@ Alphabetical List of All Switches Create expanded source files for source level debugging. This switch also suppresses generation of cross-reference information (see :switch:`-gnatx`). Note that this switch is not allowed if a previous - -gnatR switch has been given, since these two switches are not compatible. + ``-gnatR`` switch has been given, since these two switches are not compatible. .. index:: -gnateA (gcc) @@ -1638,7 +1636,7 @@ Alphabetical List of All Switches where implicit ``pragma Elaborate`` and ``pragma Elaborate_All`` are generated. This is useful in diagnosing elaboration circularities caused by these implicit pragmas when using the static elaboration - model. See See the section in this guide on elaboration checking for + model. See the section in this guide on elaboration checking for further details. These messages are not generated by default, and are intended only for temporary use when debugging circularity problems. @@ -2871,7 +2869,7 @@ of the pragma in the :title:`GNAT_Reference_manual`). .. index:: -gnatw_A :switch:`-gnatw_A` - *Supress warnings on anonymous allocators.* + *Suppress warnings on anonymous allocators.* .. index:: Anonymous allocators @@ -3011,7 +3009,7 @@ of the pragma in the :title:`GNAT_Reference_manual`). :switch:`-gnatw_C` *Suppress warnings on unknown condition in Compile_Time_Warning.* - This switch supresses warnings on a pragma Compile_Time_Warning + This switch suppresses warnings on a pragma Compile_Time_Warning or Compile_Time_Error whose condition has a value that is not known at compile time. @@ -3367,7 +3365,7 @@ of the pragma in the :title:`GNAT_Reference_manual`). This switch activates warnings for declarations that declare a name that is defined in package Standard. Such declarations can be confusing, especially since the names in package Standard continue to be directly - visible, meaning that use visibiliy on such redeclared names does not + visible, meaning that use visibility on such redeclared names does not work as expected. Names of discriminants and components in records are not included in this check. diff --git a/gcc/ada/doc/gnat_ugn/the_gnat_compilation_model.rst b/gcc/ada/doc/gnat_ugn/the_gnat_compilation_model.rst index 363670300e3..77a2055f642 100644 --- a/gcc/ada/doc/gnat_ugn/the_gnat_compilation_model.rst +++ b/gcc/ada/doc/gnat_ugn/the_gnat_compilation_model.rst @@ -1974,7 +1974,7 @@ process (see the *Installing a Library with Project Files* section of the When project files are not an option, it is also possible, but not recommended, to install the library so that the sources needed to use the library are on the Ada source path and the ALI files & libraries be on the Ada Object path (see -:ref:`Search_Paths_and_the_Run-Time_Library_RTL`. Alternatively, the system +:ref:`Search_Paths_and_the_Run-Time_Library_RTL`). Alternatively, the system administrator can place general-purpose libraries in the default compiler paths, by specifying the libraries' location in the configuration files :file:`ada_source_path` and :file:`ada_object_path`. These configuration files diff --git a/gcc/ada/gnat_ugn.texi b/gcc/ada/gnat_ugn.texi index 3d94a1ad255..f119e9fa743 100644 --- a/gcc/ada/gnat_ugn.texi +++ b/gcc/ada/gnat_ugn.texi @@ -3470,7 +3470,7 @@ process (see the `Installing a Library with Project Files' section of the When project files are not an option, it is also possible, but not recommended, to install the library so that the sources needed to use the library are on the Ada source path and the ALI files & libraries be on the Ada Object path (see -@ref{73,,Search Paths and the Run-Time Library (RTL)}. Alternatively, the system +@ref{73,,Search Paths and the Run-Time Library (RTL)}). Alternatively, the system administrator can place general-purpose libraries in the default compiler paths, by specifying the libraries’ location in the configuration files @code{ada_source_path} and @code{ada_object_path}. These configuration files @@ -8113,13 +8113,13 @@ by @code{gnatmake}. It may be necessary to use the switch @table @asis -@item `gnatmake hello.adb' +@item @code{gnatmake hello.adb} Compile all files necessary to bind and link the main program @code{hello.adb} (containing unit @code{Hello}) and bind and link the resulting object files to generate an executable file @code{hello}. -@item `gnatmake main1 main2 main3' +@item @code{gnatmake main1 main2 main3} Compile all files necessary to bind and link the main programs @code{main1.adb} (containing unit @code{Main1}), @code{main2.adb} @@ -8128,7 +8128,7 @@ Compile all files necessary to bind and link the main programs to generate three executable files @code{main1}, @code{main2} and @code{main3}. -@item `gnatmake -q Main_Unit -cargs -O2 -bargs -l' +@item @code{gnatmake -q Main_Unit -cargs -O2 -bargs -l} Compile all files necessary to bind and link the main program unit @code{Main_Unit} (from file @code{main_unit.adb}). All compilations will @@ -8191,7 +8191,7 @@ the spec of a library unit which has a body subunits @end itemize -because they are compiled as part of compiling related units. GNAT +because they are compiled as part of compiling related units. GNAT compiles package specs when the corresponding body is compiled, and subunits when the parent is compiled. @@ -8241,8 +8241,6 @@ two output files in the current directory, but you may specify a source file in any directory using an absolute or relative path specification containing the directory information. -TESTING: the @code{--foobar`NN'} switch - @geindex gnat1 @code{gcc} is actually a driver program that looks at the extensions of @@ -8329,7 +8327,7 @@ names separated by colons (semicolons when working with the NT version). The content of the @code{ada_source_path} file which is part of the GNAT installation tree and is used to store standard libraries such as the GNAT Run Time Library (RTL) source files. -@ref{72,,Installing a library} +See also @ref{72,,Installing a library}. @end itemize Specifying the switch @code{-I-} @@ -8429,7 +8427,7 @@ $ gcc -c -O2 -gnata xyz-def.adb @end example Compile the child unit package in file @code{xyz-def.adb} with extensive -optimizations, and pragma @code{Assert}/@cite{Debug} statements +optimizations, and pragma @code{Assert}/@code{Debug} statements enabled. @example @@ -8599,7 +8597,7 @@ This can also speed up the compilation of big programs and reduce the size of the executable, compared with a traditional per-unit compilation with inlining across units enabled by the @code{-gnatn} switch. The drawback of this approach is that it may require more memory and that -the debugging information generated by -g with it might be hardly usable. +the debugging information generated by @code{-g} with it might be hardly usable. The switch, as well as the accompanying @code{-Ox} switches, must be specified both for the compilation and the link phases. If the @code{n} parameter is specified, the optimization and final code @@ -8886,7 +8884,7 @@ Generate CodePeer intermediate format (no code generation attempted). This switch will generate an intermediate representation suitable for use by CodePeer (@code{.scil} files). This switch is not compatible with code generation (it will, among other things, disable some switches such -as -gnatn, and enable others such as -gnata). +as @code{-gnatn}, and enable others such as @code{-gnata}). @end table @geindex -gnatd (gcc) @@ -8900,9 +8898,9 @@ Specify debug options for the compiler. The string of characters after the @code{-gnatd} specifies the specific debug options. The possible characters are 0-9, a-z, A-Z, optionally preceded by a dot or underscore. See compiler source file @code{debug.adb} for details of the implemented -debug options. Certain debug options are relevant to applications +debug options. Certain debug options are relevant to application programmers, and these are documented at appropriate points in this -users guide. +user’s guide. @end table @geindex -gnatD[nn] (gcc) @@ -8915,7 +8913,7 @@ users guide. Create expanded source files for source level debugging. This switch also suppresses generation of cross-reference information (see @code{-gnatx}). Note that this switch is not allowed if a previous --gnatR switch has been given, since these two switches are not compatible. +@code{-gnatR} switch has been given, since these two switches are not compatible. @end table @geindex -gnateA (gcc) @@ -9114,7 +9112,7 @@ messages showing where implicit @code{pragma Elaborate} and @code{pragma Elaborate_All} are generated. This is useful in diagnosing elaboration circularities caused by these implicit pragmas when using the static elaboration -model. See See the section in this guide on elaboration checking for +model. See the section in this guide on elaboration checking for further details. These messages are not generated by default, and are intended only for temporary use when debugging circularity problems. @end table @@ -10839,7 +10837,7 @@ RM 3.10.2 (14). @item @code{-gnatw_A} -`Supress warnings on anonymous allocators.' +`Suppress warnings on anonymous allocators.' @geindex Anonymous allocators @@ -11022,7 +11020,7 @@ The default is that such warnings are generated. `Suppress warnings on unknown condition in Compile_Time_Warning.' -This switch supresses warnings on a pragma Compile_Time_Warning +This switch suppresses warnings on a pragma Compile_Time_Warning or Compile_Time_Error whose condition has a value that is not known at compile time. @end table @@ -11502,7 +11500,7 @@ This switch disables warnings on variables that could be declared constants. This switch activates warnings for declarations that declare a name that is defined in package Standard. Such declarations can be confusing, especially since the names in package Standard continue to be directly -visible, meaning that use visibiliy on such redeclared names does not +visible, meaning that use visibility on such redeclared names does not work as expected. Names of discriminants and components in records are not included in this check. @end table