Re: [PATCH] docs: kbuild/kconfig: reformat/cleanup

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



On Fri, Jan 12, 2024 at 9:58 PM Vegard Nossum <vegard.nossum@xxxxxxxxxx> wrote:
>
> This document was using headings in an odd way, causing the sidebar to be
> quite messy. I've adding new headings and turned some of the old headings
> into description lists.
>
> The indentation was a mix of spaces and tabs; I've turned them all into
> 4 spaces so it always reads correctly regardless of tab settings.
>
> Also use ``...`` instead of `...`; the difference is that `` is meant
> for "inline literals" (and renders in a monospace font) while ` is for
> "interpreted text" (and renders with italics).
>
> Also changed the title of the document to be more descriptive.
>
> Signed-off-by: Vegard Nossum <vegard.nossum@xxxxxxxxxx>


Applied to linux-kbuild.
Thanks.


> ---
>  Documentation/kbuild/kconfig.rst | 363 ++++++++++++++-----------------
>  1 file changed, 166 insertions(+), 197 deletions(-)
>
> diff --git a/Documentation/kbuild/kconfig.rst b/Documentation/kbuild/kconfig.rst
> index c946eb44bd13..fc4e845bc249 100644
> --- a/Documentation/kbuild/kconfig.rst
> +++ b/Documentation/kbuild/kconfig.rst
> @@ -1,10 +1,10 @@
> -===================
> -Kconfig make config
> -===================
> +=================================
> +Configuration targets and editors
> +=================================
>
> -This file contains some assistance for using `make *config`.
> +This file contains some assistance for using ``make *config``.
>
> -Use "make help" to list all of the possible configuration targets.
> +Use ``make help`` to list all of the possible configuration targets.
>
>  The xconfig ('qconf'), menuconfig ('mconf'), and nconfig ('nconf')
>  programs also have embedded help text.  Be sure to check that for
> @@ -12,8 +12,9 @@ navigation, search, and other general help text.
>
>  The gconfig ('gconf') program has limited help text.
>
> +
>  General
> --------
> +=======
>
>  New kernel releases often introduce new config symbols.  Often more
>  important, new kernel releases may rename config symbols.  When
> @@ -24,118 +25,102 @@ symbols have been introduced.
>
>  To see a list of new config symbols, use::
>
> -       cp user/some/old.config .config
> -       make listnewconfig
> +    cp user/some/old.config .config
> +    make listnewconfig
>
>  and the config program will list any new symbols, one per line.
>
>  Alternatively, you can use the brute force method::
>
> -       make oldconfig
> -       scripts/diffconfig .config.old .config | less
> -
> -----------------------------------------------------------------------
> -
> -Environment variables for `*config`
> +    make oldconfig
> +    scripts/diffconfig .config.old .config | less
>
> -KCONFIG_CONFIG
> ---------------
> -This environment variable can be used to specify a default kernel config
> -file name to override the default name of ".config".
>
> -KCONFIG_DEFCONFIG_LIST
> -----------------------
> +Environment variables
> +=====================
>
> -This environment variable specifies a list of config files which can be used
> -as a base configuration in case the .config does not exist yet. Entries in
> -the list are separated with whitespaces to each other, and the first one
> -that exists is used.
> +Environment variables for ``*config``:
>
> -KCONFIG_OVERWRITECONFIG
> ------------------------
> -If you set KCONFIG_OVERWRITECONFIG in the environment, Kconfig will not
> -break symlinks when .config is a symlink to somewhere else.
> +``KCONFIG_CONFIG``
> +    This environment variable can be used to specify a default kernel config
> +    file name to override the default name of ".config".
>
> -KCONFIG_WARN_UNKNOWN_SYMBOLS
> -----------------------------
> -This environment variable makes Kconfig warn about all unrecognized
> -symbols in the config input.
> +``KCONFIG_DEFCONFIG_LIST``
> +    This environment variable specifies a list of config files which can be
> +    used as a base configuration in case the .config does not exist yet.
> +    Entries in the list are separated with whitespaces to each other, and
> +    the first one that exists is used.
>
> -KCONFIG_WERROR
> ---------------
> -If set, Kconfig treats warnings as errors.
> +``KCONFIG_OVERWRITECONFIG``
> +    If you set KCONFIG_OVERWRITECONFIG in the environment, Kconfig will not
> +    break symlinks when .config is a symlink to somewhere else.
>
> -`CONFIG_`
> ----------
> -If you set `CONFIG_` in the environment, Kconfig will prefix all symbols
> -with its value when saving the configuration, instead of using the default,
> -`CONFIG_`.
> +``KCONFIG_WARN_UNKNOWN_SYMBOLS``
> +    This environment variable makes Kconfig warn about all unrecognized
> +    symbols in the config input.
>
> -----------------------------------------------------------------------
> +``KCONFIG_WERROR``
> +    If set, Kconfig treats warnings as errors.
>
> -Environment variables for '{allyes/allmod/allno/rand}config'
> +``CONFIG_``
> +    If you set ``CONFIG_`` in the environment, Kconfig will prefix all symbols
> +    with its value when saving the configuration, instead of using the
> +    default, ``CONFIG_``.
>
> -KCONFIG_ALLCONFIG
> ------------------
> -(partially based on lkml email from/by Rob Landley, re: miniconfig)
> +Environment variables for ``{allyes/allmod/allno/rand}config``:
>
> ---------------------------------------------------
> +``KCONFIG_ALLCONFIG``
> +    The allyesconfig/allmodconfig/allnoconfig/randconfig variants can also
> +    use the environment variable KCONFIG_ALLCONFIG as a flag or a filename
> +    that contains config symbols that the user requires to be set to a
> +    specific value.  If KCONFIG_ALLCONFIG is used without a filename where
> +    KCONFIG_ALLCONFIG == "" or KCONFIG_ALLCONFIG == "1", ``make *config``
> +    checks for a file named "all{yes/mod/no/def/random}.config"
> +    (corresponding to the ``*config`` command that was used) for symbol values
> +    that are to be forced.  If this file is not found, it checks for a
> +    file named "all.config" to contain forced values.
>
> -The allyesconfig/allmodconfig/allnoconfig/randconfig variants can also
> -use the environment variable KCONFIG_ALLCONFIG as a flag or a filename
> -that contains config symbols that the user requires to be set to a
> -specific value.  If KCONFIG_ALLCONFIG is used without a filename where
> -KCONFIG_ALLCONFIG == "" or KCONFIG_ALLCONFIG == "1", `make *config`
> -checks for a file named "all{yes/mod/no/def/random}.config"
> -(corresponding to the `*config` command that was used) for symbol values
> -that are to be forced.  If this file is not found, it checks for a
> -file named "all.config" to contain forced values.
> +    This enables you to create "miniature" config (miniconfig) or custom
> +    config files containing just the config symbols that you are interested
> +    in.  Then the kernel config system generates the full .config file,
> +    including symbols of your miniconfig file.
>
> -This enables you to create "miniature" config (miniconfig) or custom
> -config files containing just the config symbols that you are interested
> -in.  Then the kernel config system generates the full .config file,
> -including symbols of your miniconfig file.
> -
> -This 'KCONFIG_ALLCONFIG' file is a config file which contains
> -(usually a subset of all) preset config symbols.  These variable
> -settings are still subject to normal dependency checks.
> -
> -Examples::
> +    This ``KCONFIG_ALLCONFIG`` file is a config file which contains
> +    (usually a subset of all) preset config symbols.  These variable
> +    settings are still subject to normal dependency checks.
>
> -       KCONFIG_ALLCONFIG=custom-notebook.config make allnoconfig
> +    Examples::
>
> -or::
> +        KCONFIG_ALLCONFIG=custom-notebook.config make allnoconfig
>
> -       KCONFIG_ALLCONFIG=mini.config make allnoconfig
> +    or::
>
> -or::
> +        KCONFIG_ALLCONFIG=mini.config make allnoconfig
>
> -       make KCONFIG_ALLCONFIG=mini.config allnoconfig
> +    or::
>
> -These examples will disable most options (allnoconfig) but enable or
> -disable the options that are explicitly listed in the specified
> -mini-config files.
> +        make KCONFIG_ALLCONFIG=mini.config allnoconfig
>
> -----------------------------------------------------------------------
> +    These examples will disable most options (allnoconfig) but enable or
> +    disable the options that are explicitly listed in the specified
> +    mini-config files.
>
> -Environment variables for 'randconfig'
> +Environment variables for ``randconfig``:
>
> -KCONFIG_SEED
> -------------
> -You can set this to the integer value used to seed the RNG, if you want
> -to somehow debug the behaviour of the kconfig parser/frontends.
> -If not set, the current time will be used.
> +``KCONFIG_SEED``
> +    You can set this to the integer value used to seed the RNG, if you want
> +    to somehow debug the behaviour of the kconfig parser/frontends.
> +    If not set, the current time will be used.
>
> -KCONFIG_PROBABILITY
> --------------------
> -This variable can be used to skew the probabilities. This variable can
> -be unset or empty, or set to three different formats:
> +``KCONFIG_PROBABILITY``
> +    This variable can be used to skew the probabilities. This variable can
> +    be unset or empty, or set to three different formats:
>
>      =======================     ==================  =====================
> -       KCONFIG_PROBABILITY     y:n split           y:m:n split
> +    KCONFIG_PROBABILITY         y:n split           y:m:n split
>      =======================     ==================  =====================
> -       unset or empty          50  : 50            33  : 33  : 34
> -       N                        N  : 100-N         N/2 : N/2 : 100-N
> +    unset or empty              50  : 50            33  : 33  : 34
> +    N                            N  : 100-N         N/2 : N/2 : 100-N
>      [1] N:M                     N+M : 100-(N+M)      N  :  M  : 100-(N+M)
>      [2] N:M:L                    N  : 100-N          M  :  L  : 100-(M+L)
>      =======================     ==================  =====================
> @@ -149,112 +134,98 @@ that:
>
>  Examples::
>
> -       KCONFIG_PROBABILITY=10
> -               10% of booleans will be set to 'y', 90% to 'n'
> -               5% of tristates will be set to 'y', 5% to 'm', 90% to 'n'
> -       KCONFIG_PROBABILITY=15:25
> -               40% of booleans will be set to 'y', 60% to 'n'
> -               15% of tristates will be set to 'y', 25% to 'm', 60% to 'n'
> -       KCONFIG_PROBABILITY=10:15:15
> -               10% of booleans will be set to 'y', 90% to 'n'
> -               15% of tristates will be set to 'y', 15% to 'm', 70% to 'n'
> +    KCONFIG_PROBABILITY=10
> +        10% of booleans will be set to 'y', 90% to 'n'
> +        5% of tristates will be set to 'y', 5% to 'm', 90% to 'n'
> +    KCONFIG_PROBABILITY=15:25
> +        40% of booleans will be set to 'y', 60% to 'n'
> +        15% of tristates will be set to 'y', 25% to 'm', 60% to 'n'
> +    KCONFIG_PROBABILITY=10:15:15
> +        10% of booleans will be set to 'y', 90% to 'n'
> +        15% of tristates will be set to 'y', 15% to 'm', 70% to 'n'
>
> -----------------------------------------------------------------------
> +Environment variables for ``syncconfig``:
>
> -Environment variables for 'syncconfig'
> +``KCONFIG_NOSILENTUPDATE``
> +    If this variable has a non-blank value, it prevents silent kernel
> +    config updates (requires explicit updates).
>
> -KCONFIG_NOSILENTUPDATE
> -----------------------
> -If this variable has a non-blank value, it prevents silent kernel
> -config updates (requires explicit updates).
> +``KCONFIG_AUTOCONFIG``
> +    This environment variable can be set to specify the path & name of the
> +    "auto.conf" file.  Its default value is "include/config/auto.conf".
>
> -KCONFIG_AUTOCONFIG
> -------------------
> -This environment variable can be set to specify the path & name of the
> -"auto.conf" file.  Its default value is "include/config/auto.conf".
> +``KCONFIG_AUTOHEADER``
> +    This environment variable can be set to specify the path & name of the
> +    "autoconf.h" (header) file.
> +    Its default value is "include/generated/autoconf.h".
>
> -KCONFIG_AUTOHEADER
> -------------------
> -This environment variable can be set to specify the path & name of the
> -"autoconf.h" (header) file.
> -Its default value is "include/generated/autoconf.h".
> -
> -
> -----------------------------------------------------------------------
>
>  menuconfig
> -----------
> -
> -SEARCHING for CONFIG symbols
> +==========
>
>  Searching in menuconfig:
>
> -       The Search function searches for kernel configuration symbol
> -       names, so you have to know something close to what you are
> -       looking for.
> +    The Search function searches for kernel configuration symbol
> +    names, so you have to know something close to what you are
> +    looking for.
>
> -       Example::
> +    Example::
>
> -               /hotplug
> -               This lists all config symbols that contain "hotplug",
> -               e.g., HOTPLUG_CPU, MEMORY_HOTPLUG.
> +        /hotplug
> +        This lists all config symbols that contain "hotplug",
> +        e.g., HOTPLUG_CPU, MEMORY_HOTPLUG.
>
> -       For search help, enter / followed by TAB-TAB (to highlight
> -       <Help>) and Enter.  This will tell you that you can also use
> -       regular expressions (regexes) in the search string, so if you
> -       are not interested in MEMORY_HOTPLUG, you could try::
> +    For search help, enter / followed by TAB-TAB (to highlight
> +    <Help>) and Enter.  This will tell you that you can also use
> +    regular expressions (regexes) in the search string, so if you
> +    are not interested in MEMORY_HOTPLUG, you could try::
>
> -               /^hotplug
> +        /^hotplug
>
> -       When searching, symbols are sorted thus:
> +    When searching, symbols are sorted thus:
>
> -         - first, exact matches, sorted alphabetically (an exact match
> -           is when the search matches the complete symbol name);
> -         - then, other matches, sorted alphabetically.
> +    - first, exact matches, sorted alphabetically (an exact match
> +      is when the search matches the complete symbol name);
> +    - then, other matches, sorted alphabetically.
>
> -       For example: ^ATH.K matches:
> +    For example, ^ATH.K matches:
>
> -           ATH5K ATH9K ATH5K_AHB ATH5K_DEBUG [...] ATH6KL ATH6KL_DEBUG
> -           [...] ATH9K_AHB ATH9K_BTCOEX_SUPPORT ATH9K_COMMON [...]
> +        ATH5K ATH9K ATH5K_AHB ATH5K_DEBUG [...] ATH6KL ATH6KL_DEBUG
> +        [...] ATH9K_AHB ATH9K_BTCOEX_SUPPORT ATH9K_COMMON [...]
>
> -       of which only ATH5K and ATH9K match exactly and so are sorted
> -       first (and in alphabetical order), then come all other symbols,
> -       sorted in alphabetical order.
> +    of which only ATH5K and ATH9K match exactly and so are sorted
> +    first (and in alphabetical order), then come all other symbols,
> +    sorted in alphabetical order.
>
> -       In this menu, pressing the key in the (#) prefix will jump
> -       directly to that location. You will be returned to the current
> -       search results after exiting this new menu.
> +    In this menu, pressing the key in the (#) prefix will jump
> +    directly to that location. You will be returned to the current
> +    search results after exiting this new menu.
>
> -----------------------------------------------------------------------
> +User interface options for 'menuconfig':
>
> -User interface options for 'menuconfig'
> +``MENUCONFIG_COLOR``
> +    It is possible to select different color themes using the variable
> +    MENUCONFIG_COLOR.  To select a theme use::
>
> -MENUCONFIG_COLOR
> -----------------
> -It is possible to select different color themes using the variable
> -MENUCONFIG_COLOR.  To select a theme use::
> +        make MENUCONFIG_COLOR=<theme> menuconfig
>
> -       make MENUCONFIG_COLOR=<theme> menuconfig
> +    Available themes are::
>
> -Available themes are::
> +      - mono       => selects colors suitable for monochrome displays
> +      - blackbg    => selects a color scheme with black background
> +      - classic    => theme with blue background. The classic look
> +      - bluetitle  => a LCD friendly version of classic. (default)
>
> -  - mono       => selects colors suitable for monochrome displays
> -  - blackbg    => selects a color scheme with black background
> -  - classic    => theme with blue background. The classic look
> -  - bluetitle  => a LCD friendly version of classic. (default)
> +``MENUCONFIG_MODE``
> +    This mode shows all sub-menus in one large tree.
>
> -MENUCONFIG_MODE
> ----------------
> -This mode shows all sub-menus in one large tree.
> +    Example::
>
> -Example::
> +        make MENUCONFIG_MODE=single_menu menuconfig
>
> -       make MENUCONFIG_MODE=single_menu menuconfig
> -
> -----------------------------------------------------------------------
>
>  nconfig
> --------
> +=======
>
>  nconfig is an alternate text-based configurator.  It lists function
>  keys across the bottom of the terminal (window) that execute commands.
> @@ -266,61 +237,59 @@ Use F1 for Global help or F3 for the Short help menu.
>
>  Searching in nconfig:
>
> -       You can search either in the menu entry "prompt" strings
> -       or in the configuration symbols.
> +    You can search either in the menu entry "prompt" strings
> +    or in the configuration symbols.
> +
> +    Use / to begin a search through the menu entries.  This does
> +    not support regular expressions.  Use <Down> or <Up> for
> +    Next hit and Previous hit, respectively.  Use <Esc> to
> +    terminate the search mode.
>
> -       Use / to begin a search through the menu entries.  This does
> -       not support regular expressions.  Use <Down> or <Up> for
> -       Next hit and Previous hit, respectively.  Use <Esc> to
> -       terminate the search mode.
> +    F8 (SymSearch) searches the configuration symbols for the
> +    given string or regular expression (regex).
>
> -       F8 (SymSearch) searches the configuration symbols for the
> -       given string or regular expression (regex).
> +    In the SymSearch, pressing the key in the (#) prefix will
> +    jump directly to that location. You will be returned to the
> +    current search results after exiting this new menu.
>
> -       In the SymSearch, pressing the key in the (#) prefix will
> -       jump directly to that location. You will be returned to the
> -       current search results after exiting this new menu.
> +Environment variables:
>
> -NCONFIG_MODE
> -------------
> -This mode shows all sub-menus in one large tree.
> +``NCONFIG_MODE``
> +    This mode shows all sub-menus in one large tree.
>
> -Example::
> +    Example::
>
> -       make NCONFIG_MODE=single_menu nconfig
> +        make NCONFIG_MODE=single_menu nconfig
>
> -----------------------------------------------------------------------
>
>  xconfig
> --------
> +=======
>
>  Searching in xconfig:
>
> -       The Search function searches for kernel configuration symbol
> -       names, so you have to know something close to what you are
> -       looking for.
> -
> -       Example::
> +    The Search function searches for kernel configuration symbol
> +    names, so you have to know something close to what you are
> +    looking for.
>
> -               Ctrl-F hotplug
> +    Example::
>
> -       or::
> +        Ctrl-F hotplug
>
> -               Menu: File, Search, hotplug
> +    or::
>
> -       lists all config symbol entries that contain "hotplug" in
> -       the symbol name.  In this Search dialog, you may change the
> -       config setting for any of the entries that are not grayed out.
> -       You can also enter a different search string without having
> -       to return to the main menu.
> +        Menu: File, Search, hotplug
>
> +    lists all config symbol entries that contain "hotplug" in
> +    the symbol name.  In this Search dialog, you may change the
> +    config setting for any of the entries that are not grayed out.
> +    You can also enter a different search string without having
> +    to return to the main menu.
>
> -----------------------------------------------------------------------
>
>  gconfig
> --------
> +=======
>
>  Searching in gconfig:
>
> -       There is no search command in gconfig.  However, gconfig does
> -       have several different viewing choices, modes, and options.
> +    There is no search command in gconfig.  However, gconfig does
> +    have several different viewing choices, modes, and options.
> --
> 2.34.1
>


-- 
Best Regards
Masahiro Yamada





[Index of Archives]     [Kernel Newbies]     [Security]     [Netfilter]     [Bugtraq]     [Linux FS]     [Yosemite Forum]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux