Skip to content

Commit 3db2917

Browse files
committed
[clang] [docs] Improve formatting & fix typo in config docs
Fix teletype formatting in configuration file documentation to use double backticks rather than single backticks. Cover some more names with this formatting. Correct the name of config file for `clang-cl` invocation. Differential Revision: https://reviews.llvm.org/D134271
1 parent 48ffd40 commit 3db2917

File tree

1 file changed

+23
-23
lines changed

1 file changed

+23
-23
lines changed

clang/docs/UsersManual.rst

+23-23
Original file line numberDiff line numberDiff line change
@@ -881,9 +881,9 @@ Configuration files
881881
Configuration files group command-line options and allow all of them to be
882882
specified just by referencing the configuration file. They may be used, for
883883
example, to collect options required to tune compilation for particular
884-
target, such as -L, -I, -l, --sysroot, codegen options, etc.
884+
target, such as ``-L``, ``-I``, ``-l``, ``--sysroot``, codegen options, etc.
885885

886-
The command line option `--config` can be used to specify configuration
886+
The command line option ``--config`` can be used to specify configuration
887887
file in a Clang invocation. For example:
888888

889889
::
@@ -900,39 +900,39 @@ treated as a file name and is searched for sequentially in the directories:
900900
- the directory where Clang executable resides.
901901

902902
Both user and system directories for configuration files are specified during
903-
clang build using CMake parameters, CLANG_CONFIG_FILE_USER_DIR and
904-
CLANG_CONFIG_FILE_SYSTEM_DIR respectively. The first file found is used. It is
905-
an error if the required file cannot be found.
903+
clang build using CMake parameters, ``CLANG_CONFIG_FILE_USER_DIR`` and
904+
``CLANG_CONFIG_FILE_SYSTEM_DIR`` respectively. The first file found is used.
905+
It is an error if the required file cannot be found.
906906

907907
If no explicit configuration file is specified, Clang searches for a default
908908
configuration file following the rules described in the next paragraphs.
909-
To disable this behavior, `--no-default-config` flag can be used.
909+
To disable this behavior, ``--no-default-config`` flag can be used.
910910

911911
Another way to specify a configuration file is to encode it in executable name.
912-
For example, if the Clang executable is named `armv7l-clang` (it may be a
913-
symbolic link to `clang`), then Clang will search for file `armv7l.cfg` in the
914-
directory where Clang resides.
912+
For example, if the Clang executable is named ``armv7l-clang`` (it may be a
913+
symbolic link to ``clang``), then Clang will search for file ``armv7l.cfg``
914+
in the directory where Clang resides.
915915

916916
If a driver mode is specified in invocation, Clang tries to find a file specific
917917
for the specified mode. For example, if the executable file is named
918-
`x86_64-clang-cl`, Clang first looks for `x86_64-cl.cfg` and if it is not found,
919-
looks for `x86_64.cfg`.
918+
``x86_64-clang-cl``, Clang first looks for ``x86_64-clang-cl.cfg`` and if it is
919+
not found, looks for ``x86_64.cfg``.
920920

921921
If the command line contains options that effectively change target architecture
922-
(these are -m32, -EL, and some others) and the configuration file starts with an
923-
architecture name, Clang tries to load the configuration file for the effective
924-
architecture. For example, invocation:
922+
(these are ``-m32``, ``-EL``, and some others) and the configuration file starts
923+
with an architecture name, Clang tries to load the configuration file for the
924+
effective architecture. For example, invocation:
925925

926926
::
927927

928928
x86_64-clang -m32 abc.c
929929

930-
causes Clang search for a file `i368.cfg` first, and if no such file is found,
931-
Clang looks for the file `x86_64.cfg`.
930+
causes Clang search for a file ``i368.cfg`` first, and if no such file is found,
931+
Clang looks for the file ``x86_64.cfg``.
932932

933933
The configuration file consists of command-line options specified on one or
934934
more lines. Lines composed of whitespace characters only are ignored as well as
935-
lines in which the first non-blank character is `#`. Long options may be split
935+
lines in which the first non-blank character is ``#``. Long options may be split
936936
between several lines by a trailing backslash. Here is example of a
937937
configuration file:
938938

@@ -948,19 +948,19 @@ configuration file:
948948
# other config files may be included
949949
@linux.options
950950

951-
Files included by `@file` directives in configuration files are resolved
951+
Files included by ``@file`` directives in configuration files are resolved
952952
relative to the including file. For example, if a configuration file
953-
`~/.llvm/target.cfg` contains the directive `@os/linux.opts`, the file
954-
`linux.opts` is searched for in the directory `~/.llvm/os`.
953+
``~/.llvm/target.cfg`` contains the directive ``@os/linux.opts``, the file
954+
``linux.opts`` is searched for in the directory ``~/.llvm/os``.
955955

956-
To generate paths relative to the configuration file, the `<CFGDIR>` token may
956+
To generate paths relative to the configuration file, the ``<CFGDIR>`` token may
957957
be used. This will expand to the absolute path of the directory containing the
958958
configuration file.
959959

960960
In cases where a configuration file is deployed alongside SDK contents, the
961-
SDK directory can remain fully portable by using `<CFGDIR>` prefixed paths.
961+
SDK directory can remain fully portable by using ``<CFGDIR>`` prefixed paths.
962962
In this way, the user may only need to specify a root configuration file with
963-
`--config` to establish every aspect of the SDK with the compiler:
963+
``--config`` to establish every aspect of the SDK with the compiler:
964964

965965
::
966966

0 commit comments

Comments
 (0)