Question about notation in `man taskrc`

[bradyt]

trafficstars

Is man taskrc meant to report current values, or default values?

The format looks like this

x=y
       May be "y" or "z". This setting is to indicate the positioning of the widget. The default value is "z".

I check the current, local and default value, and it's x=z. I'm curious what x=y is meant to represent, especially as it's hardcoded into the manual.

Was that line to represent the default value, or the local value? If it represents the default value, then it is redundant to the last line describing the default value, which I won't protest to. If it's meant to represent the local value, it's hard-coded.

Here is the specific example:

> task show | grep all.tags
complete.all.tags                  0
list.all.tags                      0
> man taskrc
...
complete.all.tags=1
       May be "1" or "0", and determines whether the tab completion scripts
       consider all the tag names you have used, or just the ones used in active
       tasks. The default value is "0".
list.all.tags=1
       May be "1" or "0", and determines whether the 'tags' command lists all
       the tag names you have used, or just the ones used in active tasks. The
       default value is "0".

[smemsh]

Man pages are static, generated at build time. The entries you mention presumably just show example values. The only part of the man page that's even generated at build time rather than just embedded in the man page source is the version:

 $ diff -u doc/man/taskrc.5*
--- doc/man/taskrc.5    2021-10-25 22:22:22.683637287 -0700
+++ doc/man/taskrc.5.in 2021-10-09 19:41:38.165364361 -0700
@@ -1,4 +1,4 @@
-.TH taskrc 5 2016-02-24 "task 2.6.1" "User Manuals"
+.TH taskrc 5 2016-02-24 "${PACKAGE_STRING}" "User Manuals"

I don't think this is a bug, this is just how man pages work. If I understand what you mean, dynamic man pages that get values by reading config files at display-time sounds interesting, but isn't how man pages ever worked and sounds like a security and performance challenge.

Putting defaults in the man pages as variables to be filled at build-time from constants in the source would be both possible and useful (I have seen this in other projects), but in the meantime, it looks like the defaults are already shown in the paragraphs that explain the settings.

[bradyt]

I'm afraid I just got confused. With your explanation, I agree there may not be anything to change. This issue might be "support".

If variables are put in for defaults in man pages, that might conflict with examples I just noticed, like the following, which provide multiple example values, not just the default.

   MISCELLANEOUS
       verbose=1|0|nothing|list...
              When set to "1" (the default), helpful explanatory comments are added to all output from Taskwarrior. Setting
              this to "0" means that you would see regular output.
...
       expressions=infix|postfix
              Sets a preference for infix expressions (1 + 2) or postfix expressions (1 2 +).  Defaults to infix.

And I suspect man taskdrc has some example values that are deliberately not set as default.

Just bringing these up in case it's relevant to considering the variables feature.

Sounds very low priority, at best, and the question as originally asked seems to be fixed.

Please feel free to do any or all of close, use, defer, repurpose, retitle, the issue as you like.