lib/sh/util.sh: logging: log_level definition: added instructions to view a message's log_level (count the # of + signs before it in the output)

lib/sh/util.sh: logging: log_level definition: replaced command with message because not just commands can be logged

lib/sh/util.sh: logging: log_level definition: emphasized that the log_level starts with 1, not 0 (0 has a special meaning, which refers to unfiltered messages)

lib/sh/util.sh: logging: log_level definition: documented that for commands that use can_log(), the log_level starts with 1. for unfiltered commands, the log_level is 0 (i.e. still output at verbosity=0).

lib/sh/util.sh: logging: added definition that the log_level is the minimum verbosity needed to display a command

lib/sh/util.sh: set_global_fds(): documented that the logging output for this is visible at verbosity >= 3

lib/sh/util.sh: set_global_fds(): moved stdlog fd setup to separate setup_log_fd() function, which runs at a much higher log_level (5 instead of 3). because the stdlog fd setup statements themselves are logged to fd 2 (because fd 30 is not yet open), you normally don't want to display these, if you are using fd 2 for errors only and fd 30 for logging.

lib/sh/util.sh: command(): $cmd_log_fd: if not set, assume it's a script using util.sh (i.e. with log fd=$log_fd)

lib/sh/util.sh: set_global_fds(): also open stdlog logging stream on fd 30, and use this in the logging functions by setting $log_fd

lib/sh/util.sh: moved streams section before external commands echoing because command() uses set_fds

lib/sh/util.sh: moved echo_eval() to general command echoing section so it can be used by other echoing commands

lib/sh/util.sh: don't load new aliases after defining echo_stdout because it's no longer an alias

lib/sh/util.sh: load new aliases after defining echo_func

lib/sh/util.sh: .(): use "$FUNCNAME" like cd()

lib/sh/util.sh: .(): wrapped lines in the same way as cd()

lib/sh/util.sh: moved functions echoing section before other types of echoing so they can use echo_func()

lib/sh/util.sh: $verbosity: decreased default value to 1 so that normally, only external commands are echoed. this avoids cluttering up the output with the function call tree, which is really only needed for debugging. it also mirrors make's default verbosity (i.e. print external commands and subdir recursions, but not make's internal actions).

*{.sh,run}: put doc comment on next line when possible, so that the function name always comes before it

lib/sh/util.sh: put usage message at end of line when possible, so that the function name always comes before it

bugfix: lib/sh/util.sh: $top_script: need to realpath this before doing any cd so this points to the right place. set and use $top_script_abs for this purpose.

lib/runscripts/util.run: added setting of $top_file, $top_filename to set_paths()

lib/runscripts/util.run: set $top_file, $top_filename in a function (set_paths__util_run())

lib/sh/util.sh: cd(): re-run set_paths() to update $top_script, $top_dir for the new current dir

lib/sh/util.sh: added set_paths(), which sets $top_script, $top_dir

lib/sh/util.sh: moved $top_script, $top_dir before internal commands echoing so they can be reset in cd()

lib/sh/util.sh: moved vars echoing before internal commands echoing so that echo_vars can be used in it

lib/sh/util.sh: use set_fds() instead of `echo_eval exec` for clarity

lib/sh/util.sh: set_fd(): allow setting multiple fds at once, and changed the function name accordingly

lib/sh/util.sh: set_fd(): moved noclobber functionality to fd_set_default() since that is only used by fd_set_default() (whose purpose has become just to run set_fd without clobbering an existing dest fd)

lib/sh/util.sh: shadow_fd(): renamed to fd_set_default() for clarity (since this can't just be used for shadowing stdin/stdout/stderr)

lib/sh/util.sh: set_fd()/shadow_fd(): take the redirect expr as an arg instead of a kw_param because it's the only param

lib/sh/util.sh: set_fd()/shadow_fd(): take just a redirect expr containing the entire dest[<>]src expr, and parse the dest out from it

lib/sh/util.sh: set_fd()/shadow_fd(): updated usage and kw_params

lib/sh/util.sh: set_fd()/shadow_fd(): updated usage and kw_params

lib/sh/util.sh: set_fd()/shadow_fd(): take just a redirect source expr containing the <> and the fd, to allow the caller to specify these in the shell redirection syntax. this also allows using a file (such as /dev/null) as the redirect source.

lib/sh/util.sh: added cd() wrapper that logs itself and indents (indent is permanent within subshell cd was used in)

lib/sh/util.sh: added caller_indent alias

lib/sh/util.sh: log_err(): changed symbol to # instead of * so that it stands out better at the outmost indent level and doesn't blend in with the + that will be prefixing other messages

lib/sh/util.sh: log_info(): changed symbol to : so that it blends in better with the | lines (looking like a dotted segment of the line), but still stands out (because of the dots)

*{.sh,run}: don't use aliases unless it's actually necessary (e.g. to define a var in the calling function, or to alias-expand the next word)

lib/runscripts/util.run: $top_file: also match dir-level runscripts by removing /run suffix

lib/sh/util.sh: shadow_fd(): take a dest fd instead of a prefix to prepend to the src fd, so that the full name of the dest fd is in the function call. this makes it much clearer what fd will be created from a shadow_fd() call.

lib/sh/util.sh: rel_path(): also remove base_dir when path exactly = to it. this involves adding and removing an extra trailing /.

bugfix: lib/sh/util.sh: rel_path(): ensure non-empty by using . if empty

lib/sh/util.sh: split canon_rel_path() into itself and rel_path() helper for clarity

lib/sh/local.sh: $root_dir: run canon_rel_path on it

lib/sh/util.sh: log_custom(): use keyword-args syntax instead of local vars

lib/sh/util.sh: log_custom(): replace all non-whitespace chars in PS4 with $symbol instead of just the first one, so there aren't mixed $symbols and PS4 chars

lib/sh/util.sh: moved paths section after logging so it can use logging functions

*{.sh,run}: echo all global vars (except those defined before echo_vars is available)

web/links/index.htm.run: use the runscript-common $top_file, which is equivalent to $linked_file

*{.sh,run}: use new local_export instead of local...export. this still requires calling echo_vars manually, because local_export is an alias (and must be, to define the var in the caller's context).

lib/sh/util.sh: added local_export alias, which combines the effects of local and export

lib/sh/util.sh: renamed params() to kw_params() to clarify the type of params it handles

lib/sh/util.sh: logging: echo all keyword params by overriding params(). this requires removing manual echo_vars calls.

lib/sh/util.sh: moved functions section right after exceptions, so that other sections can use it. in particular, func_override is needed by verbose output to override non-verbose versions of functions.

lib/sh/util.sh: only try to echo vars that are set, to avoid `declare -p` "not found" errors

: use new `params` in all functions that have keyword params, in order to remove their vars from the environment. note that functions that use $? (such as die()) must save it *before running params, because params will overwrite $?.

web/links/index.htm: updated to Firefox bookmarks. added bash and MySQL-related bookmarks, including MySQL doc subfolder.

lib/sh/util.sh: params(): added doc comment

lib/sh/util.sh: added params(), which removes keyword-param-only vars from the environment

lib/sh/util.sh: added unexport() (note that `declare +x` won't work because it defines the var if it isn't set)

lib/sh/util.sh: moved vars section to beginning so other sections can use it (it does not contain logging statements, so it doesn't need to be after verbose output)

bugfix: lib/sh/util.sh: command(): limit cmd_log_fd directly instead of limiting log_fd (usually fd 2) and then redirecting cmd_log_fd to it. this ensures that stderr is not limited unless it's actually used as the cmd_log_fd, so that a non-logging stderr will still reach the user properly regardless of whether err_fd is set to something other than 2. (previously, without an err_fd at 22, closing fd 2 at the beginning of the set of redirections would leave no fd pointing to a place to echo errors to.)

lib/sh/util.sh: disable_logging(): use echo_eval instead of plain eval so the disabling of logging is nevertheless itself logged

lib/sh/util.sh: command(): made usage message an end-of-line comment

lib/sh/util.sh: inlined limit_log_fd into command() since it's only used once

lib/sh/util.sh: log_err(), log_info(): use bolder symbols (*, #) to make the symbol stand out visually from the line of | above and below it

lib/sh/util.sh: $verbosity: lowered the default from 3 to 2 because level 3 output (vars, etc.) is too verbose for the default output and is only needed for debugging

lib/sh/util.sh: $log_level_indent: added space after | to visually separate the nesting levels and make the output look like an expandable tree (similar to a filesystem browser tree)

lib/sh/util.sh: log_custom(): replace every non-whitespace character of $log_indent, and the first character of PS4, with the symbol, to make the symbol stand out on the line instead of the |||... before it

lib/sh/util.sh: removed no longer used stdout2log_fd(). set $cmd_log_fd instead.

lib/sh/util.sh: set $log_level_indent to | because this visually connects commands at the same indent by effectively connecting their + prefixes with a line of |

lib/sh/archives.sh: zip(), unzip(): added missing echo_func

lib/sh/util.sh: command(): use just one control var $cmd_log_fd instead of three flags (limit_log_fd, limit_stdout, stderr_is_errors) that indicated various common fd configurations. this is much clearer (you state which fd the common uses as its logging fd), more configurable (the logging fd can be any fd, not just 1 or 2), and more automatic (redirecting fd 2 to err_fd happens automatically if it isn't used for logging).

bugfix: lib/sh/local.sh: psql(): need to use limit_stdout=1 instead of stderr_is_errors=1 because logging info is output to stdout, not stderr, in spite of the >&2 redirection, since the >&2 is applied after command()'s logging redirects. note that the >&2 can now be removed, because it will be performed by command().

lib/sh/util.sh: added $log_fd and use it instead of 2 where the log_fd is intended

lib/sh/util.sh: moved stdout2log_fd() to command verbose output subsection of verbose output since it is primarily intended for use with external commands

lib/sh/util.sh: renamed limit_stderr to limit_log_fd, stdout2stderr to stdout2log_fd to clarify their purpose. log_fd is currently assumed to be 2.

lib/sh/util.sh: added disable_logging() and use it instead of `exec 2>/dev/null`

lib/sh/util.sh: added $err_fd global var and use it instead of the 22 magic value. it starts out at 2 until fd 22 has been set up, so commands that required 22 will now work before set_global_fds() is called.

lib/sh/util.sh: shadow_fd(): don't require it to be run with log++ and instead let callers apply log++ if needed. in set_global_fds(), log++ can just be applied once for all the shadow_fd() calls.

lib/sh/util.sh: shadow_fd(): instead of applying minor=1 (i.e. an additional log++) to echo_func and then log++ again separately to set_fd, just apply it to the entire function

lib/sh/util.sh: set_fd(): don't increase the log_level for this function, and instead let callers increase it if needed

lib/sh/util.sh: limit_stderr(): inlined log++ with the can_log call because it should only apply to it. this also makes it obvious that log++ should not apply outside of this function. this also enables the contents of this function to be used in an alias.

lib/sh/util.sh: command(): use exec instead of `builtin command` to avoid spawning an extra process (since a subshell is already open)

bugfix: lib/sh/util.sh: command(): only indent if command was logged

bugfix: lib/sh/util.sh: .(): only indent if include statement was logged

lib/sh/util.sh: limit_stderr(): moved $stdout2stderr to command() so that limit_stderr()'s only purpose is to log-limit stderr

bugfix: lib/sh/util.sh: limit_stderr(): moved $stderr_is_errors default to command() where it's used

lib/sh/util.sh: limit_stderr(): do stdout2stderr after limit_stderr to avoid having two similar `can_log ... >/dev/null` commands

lib/sh/util.sh: echo_cmd(): removed no longer used removal of first builtin or command arg

lib/sh/util.sh: inlined echo_run_prep into command() since it's now only used once

lib/sh/util.sh: command(): removed no longer used $cmd_echoed flag

*{.sh,run}: use new limit_stdout=1 instead of stdout2stderr=1 limit_stderr=1

lib/sh/util.sh: command(): added limit_stdout=1 flag which implies stdout2stderr=1 limit_stderr=1

lib/sh/util.sh: merged limit_stderr_cmd/limit_stdout_cmd into command(), using flag vars to control what limiting actions it needs to perform. in command invocations, this involves setting the appropriate flag vars instead of using a limit_std*_cmd alias.

lib/sh/util.sh: added run_cmd

lib/sh/util.sh: limit_stderr(): moved before command echoing because it does not depend on it and is a separate feature

lib/sh/util.sh: run_args_cmd(): use $top_script instead of `"$(canon_rel_path "$0")"`