[PATCH] doc: document config_directory and config_file variables

[PATCH] doc: document config_directory and config_file variables

[Andrey Borzenkov]

People are using this variable and it should be documented.

---
 docs/grub.texi | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/docs/grub.texi b/docs/grub.texi
index b9f41a7..db765a3 100644
--- a/docs/grub.texi
+++ b/docs/grub.texi
@@ -3038,6 +3038,8 @@ These variables have special meaning to GRUB.
 * cmdpath::
 * color_highlight::
 * color_normal::
+* config_directory::
+* config_file::
 * debug::
 * default::
 * fallback::
@@ -3180,6 +3182,22 @@ matching colors of first half.
 to support whole rgb24 palette but currently there is no compelling reason
 to go beyond the current 16 colors.
 
+
+@node config_directory
+@subsection config_directory
+
+This variable is automatically set by GRUB to the directory part of
+current configuration file name (@pxref{config_file}).
+
+
+@node config_file
+@subsection config_file
+
+This variable is automatically set by GRUB to the name of configuration file that is being
+processed by commands @command{configfile} (@pxref{configfile}) or @command{normal}
+(@pxref{normal}).  It is restored to the previous value when command completes.
+
+
 @node debug
 @subsection debug
 
-- 
tg: (c1fbc26..) u/config_directory (depends on: master)

Re: [PATCH] doc: document config_directory and config_file variables

[Vladimir 'phcoder' Serbinenko]

[-- Attachment #1: Type: text/plain, Size: 1595 bytes --]

Go ahead
Le 7 nov. 2015 11:22 AM, "Andrey Borzenkov" <arvidjaar@gmail.com> a écrit :

> People are using this variable and it should be documented.
>
> ---
>  docs/grub.texi | 18 ++++++++++++++++++
>  1 file changed, 18 insertions(+)
>
> diff --git a/docs/grub.texi b/docs/grub.texi
> index b9f41a7..db765a3 100644
> --- a/docs/grub.texi
> +++ b/docs/grub.texi
> @@ -3038,6 +3038,8 @@ These variables have special meaning to GRUB.
>  * cmdpath::
>  * color_highlight::
>  * color_normal::
> +* config_directory::
> +* config_file::
>  * debug::
>  * default::
>  * fallback::
> @@ -3180,6 +3182,22 @@ matching colors of first half.
>  to support whole rgb24 palette but currently there is no compelling reason
>  to go beyond the current 16 colors.
>
> +
> +@node config_directory
> +@subsection config_directory
> +
> +This variable is automatically set by GRUB to the directory part of
> +current configuration file name (@pxref{config_file}).
> +
> +
> +@node config_file
> +@subsection config_file
> +
> +This variable is automatically set by GRUB to the name of configuration
> file that is being
> +processed by commands @command{configfile} (@pxref{configfile}) or
> @command{normal}
> +(@pxref{normal}).  It is restored to the previous value when command
> completes.
> +
> +
>  @node debug
>  @subsection debug
>
> --
> tg: (c1fbc26..) u/config_directory (depends on: master)
>
> _______________________________________________
> Grub-devel mailing list
> Grub-devel@gnu.org
> https://lists.gnu.org/mailman/listinfo/grub-devel
>

[-- Attachment #2: Type: text/html, Size: 2079 bytes --]

Re: [PATCH] doc: document config_directory and config_file variables

[Arbiel (gmx)]

[-- Attachment #1: Type: text/plain, Size: 2185 bytes --]

Hi

There seems to be other variables and command parameters which lack
documentation.

Here is a list of such variables found in my grub.cfg files (I have
discarded "save_env"ed variables, obviously environment variables) and
which are not set in the environment block

${feature_menuentry_id}
${boot_once}
$feature_all_video_module
$feature_default_font_path
$feature_platform_search_hint
$feature_timeout_style
$match

As the names suggest, these variables could be distribution specific
(Ubuntu). What do you think ?

undocumented command parameter : --hint (command search), and some other
--hint.something which I haven't been able to localise just now.

I found in my grub.cfg file a "hwmatch" command which is not defifed as
a function. Is this a undocumented grub command ? Its result may well
the  $match variable.


Le 07/11/2015 11:21, Andrey Borzenkov a écrit :
> People are using this variable and it should be documented.
>
> ---
>  docs/grub.texi | 18 ++++++++++++++++++
>  1 file changed, 18 insertions(+)
>
> diff --git a/docs/grub.texi b/docs/grub.texi
> index b9f41a7..db765a3 100644
> --- a/docs/grub.texi
> +++ b/docs/grub.texi
> @@ -3038,6 +3038,8 @@ These variables have special meaning to GRUB.
>  * cmdpath::
>  * color_highlight::
>  * color_normal::
> +* config_directory::
> +* config_file::
>  * debug::
>  * default::
>  * fallback::
> @@ -3180,6 +3182,22 @@ matching colors of first half.
>  to support whole rgb24 palette but currently there is no compelling reason
>  to go beyond the current 16 colors.
>  
> +
> +@node config_directory
> +@subsection config_directory
> +
> +This variable is automatically set by GRUB to the directory part of
> +current configuration file name (@pxref{config_file}).
> +
> +
> +@node config_file
> +@subsection config_file
> +
> +This variable is automatically set by GRUB to the name of configuration file that is being
> +processed by commands @command{configfile} (@pxref{configfile}) or @command{normal}
> +(@pxref{normal}).  It is restored to the previous value when command completes.
> +
> +
>  @node debug
>  @subsection debug
>  



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 230 bytes --]

Re: [PATCH] doc: document config_directory and config_file variables

[Andrei Borzenkov]

07.11.2015 22:51, Arbiel (gmx) пишет:
> Hi
>
> There seems to be other variables and command parameters which lack
> documentation.
>
> Here is a list of such variables found in my grub.cfg files (I have
> discarded "save_env"ed variables, obviously environment variables) and
> which are not set in the environment block
>
> ${feature_menuentry_id}
> ${boot_once}
> $feature_all_video_module
> $feature_default_font_path
> $feature_platform_search_hint
> $feature_timeout_style

I do not not think any of them need to be documented in user manual. 
Features are of interest to developers to ensure backward compatibility; 
users start off with a given version and need not usually care if it 
works in earlier ones. $boot_once is internal implementation variable 
that is of no interest to anyone and its purpose is obvious by reading 
script.

It's fine to describe them in developers documentation of course, but so 
far nobody volunteered to maintain it.

> $match
>
> As the names suggest, these variables could be distribution specific
> (Ubuntu). What do you think ?
>
> undocumented command parameter : --hint (command search), and some other
> --hint.something which I haven't been able to localise just now.
>

Which command?

> I found in my grub.cfg file a "hwmatch" command which is not defifed as
> a function. Is this a undocumented grub command ? Its result may well
> the  $match variable.
>

Both are Ubuntu (or may be Debian) specific.

Re: [PATCH] doc: document config_directory and config_file variables

[Arbiel (gmx)]

[-- Attachment #1: Type: text/plain, Size: 2067 bytes --]



Le 07/11/2015 21:09, Andrei Borzenkov a écrit :
> 07.11.2015 22:51, Arbiel (gmx) пишет:
>> Hi
>>
>> There seems to be other variables and command parameters which lack
>> documentation.
>>
>> Here is a list of such variables found in my grub.cfg files (I have
>> discarded "save_env"ed variables, obviously environment variables) and
>> which are not set in the environment block
>>
>> ${feature_menuentry_id}
>> ${boot_once}
>> $feature_all_video_module
>> $feature_default_font_path
>> $feature_platform_search_hint
>> $feature_timeout_style
>
> I do not not think any of them need to be documented in user manual.
> Features are of interest to developers to ensure backward
> compatibility; users start off with a given version and need not
> usually care if it works in earlier ones. $boot_once is internal
> implementation variable that is of no interest to anyone and its
> purpose is obvious by reading script.
>
> It's fine to describe them in developers documentation of course, but
> so far nobody volunteered to maintain it.
>
>> $match
>>
>> As the names suggest, these variables could be distribution specific
>> (Ubuntu). What do you think ?
>>
>> undocumented command parameter : --hint (command search), and some other
>> --hint.something which I haven't been able to localise just now.
>>
>
> Which command?
search.
And I just read in a grub.cfg file, not one of mine the line

search --no-floppy --fs-uuid --set=root --hint-bios=hd0,gpt6 --hint-efi=hd0,gpt6 --hint-baremetal=ahci0,gpt6  427b86fb-cc66-46be-ad68-ade86794af55

which shows some "--hint" parameters. What do they all mean ?
>
>> I found in my grub.cfg file a "hwmatch" command which is not defifed as
>> a function. Is this a undocumented grub command ? Its result may well
>> the  $match variable.
>>
>
> Both are Ubuntu (or may be Debian) specific.
>
>
> _______________________________________________
> Grub-devel mailing list
> Grub-devel@gnu.org
> https://lists.gnu.org/mailman/listinfo/grub-devel



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 230 bytes --]

Re: [PATCH] doc: document config_directory and config_file variables

[Andrei Borzenkov]

08.11.2015 01:58, Arbiel (gmx) пишет:
>
>>>
>>> undocumented command parameter : --hint (command search), and some other
>>> --hint.something which I haven't been able to localise just now.
>>>
>>
>> Which command?
> search.
> And I just read in a grub.cfg file, not one of mine the line
>
> search --no-floppy --fs-uuid --set=root --hint-bios=hd0,gpt6 --hint-efi=hd0,gpt6 --hint-baremetal=ahci0,gpt6  427b86fb-cc66-46be-ad68-ade86794af55
>
> which shows some "--hint" parameters. What do they all mean ?

They are intended to optimize search at boot time. They contain guessed 
firmware device names. If this name was guessed correctly, it avoids 
searching across all devices at boot time.

In practice for Linux on i386-pc it does not really work because to 
reliably guess BIOS HDD number you need EDD and with 32 bit Linux boot 
protocol EDD information must be provided by bootloader.

This is again something that users should not be normally concerned with 
- these hints are added automatically by probing code. We could add "see 
development manual for additional options" if we had development manual 
... but yes, description of grub-mkconfig framework and which high-level 
functions are provided is missing.