Differences

This shows you the differences between two versions of the page.

--- user_guide:shell_custom [2019/01/25 09:27] – ↷ Page moved from tutorial:shell_custom to user_guide:shell_custom oroehrig
+++ user_guide:howto:shell_custom [2021/01/12 14:34] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
 ===== Customizing the polymake shell =====
-Here we won't speak about really mighty features like defining own rules or object types; they are described [[reference:rulefiles|elsewhere]].  Instead we'll start with tiny, easy to use tools of fine-tuning.
+Here we won't speak about really mighty features like defining own rules or object types; they are described [[user_guide:extend:rulefiles|elsewhere]].  Instead we'll start with tiny, easy to use tools of fine-tuning.
 ==== Custom variables ====
-You can tune many aspects of polymake behavior by changing values of numerous variables which are dedicated for keeping user-visible settings.  In the following these variables are called with their polymake nickname //custom variable// (which actually has been borrowed from the xemacs terminology).  The definitions of custom variables are scattered over dozens of rule files; fortunately, polymake offers two ways of accessing them in a more systematic and comfortable manner.
+You can tune many aspects of polymake behavior by changing values of numerous variables which are dedicated for keeping user-visible settings.  These variables can be grouped by their purpose into the following categories:
-  -- All definitions are repeated in a text file residing in your home directory: ''~/.polymake/customize.pl'' .  You are invited to load it in your favorite text editor and study its contents.  The variables are sorted there first by applications, then by package names.  Most of them will appear as deactivated (that is, the lines start with ''#'' which is the perl fashion of making comments to programs).  This means, the default values assigned to them somewhere in the polymake source code are in effect.  If you want to change them, simply remove the ''#'' sign and fill in your desired value.  By the way, the color values don't need to be entered in numerical RGB notation; any color name listed in the system color list addressed in ''$Visual::Color::RGBtxt_path'' can be used instead.
+  -- General appearance steering, like verbosity levels for various kinds of events, shell input history size or editor, as well as global lookup paths for extensions and user scripts.  These variables are defined in the packages ''Polymake::User'' and ''Polymake::User::Verbose''.
-  .. Some variable definitions appear accompanied by a preceding line of the form ''ARCH('//xyz//')'' .  These are special in that they are dynamically set by auto-configuration routines lurking in some rule files, and therefore potentially dependent on the computer architecture.  (Recall that you may use polymake on alternating computer platforms having different paths to programs etc.)  The preferred way of changing these variables is to use the ''[[general#Configuration|reconfigure]]'' command as described below, because with some of them additional consistency checks may be associated.  But in many cases they can be easily edited as well.
-  .. A few variables are stored in a different file: ''~/.polymake/prefer.pl'' .  They are separated from the rest because they don't belong to any application but rather control the universal facilities like history editing in the interactive shell or locating extensions.  When specifying various search paths, you may use ''~'' as an abbreviation for your home directory; other environment variables can be referred as ''$ENV{//name//}''
+  -- Customizing visualization tasks, for example, adjusting font sizes, styles or colors.  The allowed values are in general highly specific to the graphic processors, however, for colors you can everywhere use symbolic names recognized on your system.  Such variables usually have some decent default values defined in the rule files.
-  .. Please remember that you shouldn't edit any of these files as long as a polymake process is running anywhere under your account.  Sometimes polymake needs to store some changes there on its own behalf, but this happens immediately before the exit; so either your or polymake's changes will definitely be lost.
-  -- There are two interactive commands manipulating custom variables:
+  -- Configurable locations and options for running third-party software.  Usually they are set automatically by an automatic configuration routine executed during the first use of the corresponding rule file.  Sometimes the automatics can fail because of, for example, a non-standard installation, then you have the possibility to aid it with manual input.
-    ? ''%%set_custom $name=value;%%''
-    ? ''%%set_custom @name=(value, ...);%%''
+Variables with non-default and automatically configured values are persisted in your personal settings file ''~/.polymake/settings''.  It's not recommended to edit this file manually, because corrupting it might make polymake unable to start altogether.  Instead, please use appropriate polymake shell commands:
-    ? ''%%set_custom %name=(key => value, ...);%%''
-    ? ''%%set_custom $name{key}=value;%%''
+  ? ''%%set_custom $name=value;%%''
-    :: set a new value of a scalar, an array, a hash map, or a single value therein
+  ? ''%%set_custom @name=(value, ...);%%''
-    ? ''%%reset_custom $name;%%''
+  ? ''%%set_custom %name=(key => value, ...);%%''
-    ? ''%%reset_custom @name;%%''
+  ? ''%%set_custom $name{key}=value;%%''
-    ? ''%%reset_custom %name;%%''
+  :: set a new persistent value of a scalar, an array, a hash map, or a single value therein
-    ? ''%%reset_custom $name{key};%%''
+  ? ''%%reset_custom $name;%%''
-    :: restore the default value
+  ? ''%%reset_custom @name;%%''
-  .. Both commands come into effect immediately, but also mark the variable as changed, so that the new value will also appear in your personal customization file after the session end.  You can also change the custom variables for the rest of current session only, without updating the file -- by a plain assignment.  If you want to change some value temporarily, just to influence the evaluation of the next expression, write the ''local'' keyword instead of ''set_custom''.  (It's not polymake's black magic, just normal perl operator.)
+  ? ''%%reset_custom %name;%%''
+  ? ''%%reset_custom $name{key};%%''
+  :: restore the default value
+  ? ''%%local $name=value;%%'' etc.
+  :: change the value temporarily for the duration of the current shell input evaluation
+  ? ''%%reconfigure "rulefile";%%''
+  :: re-run the configuration routine in the specified rulefile where you'll be able to revise and edit calculated values
+An overview of all available custom variables can be obtained by executing ''%%help "custom";%%'' or using TAB completion for ''set_custom'' command.
 === Configuring applications ===
 There are two custom variables related to applications.  The list ''@start_applications'' contains names of all applications to be loaded at the very beginning of the interactive session (although the process of loading applications is totally transparent to you, having loaded your favorites in advance avoids annoying delays during the session).  The variable ''$default_application'' names the application to be made current at the beginning of the session.  Until you change this, it will be ''polytope'' for its undisputed merits as the oldest and most prominent application in polymake.
 ==== Preferences ====
-Preferences are lists of choice of different tools capable of performing the same task.  When polymake can't make a choice based on objective criteria, it consults the preference lists and takes the tool listed as first.  For example, there are several programs capable of drawing a 3-d polytope: javaview, povray, geomview, etc.  Another example is the convex hull computation for which up to five different algorithms (depending on the coordinate type) come into consideration.  The sensible choice between them can't be made based on some quantitative estimates; instead, your intuition and, sometimes, personal taste must take over the leadership.
+Preferences are lists of choice of different tools capable of performing the same task.  When polymake can't make a choice based on objective criteria, it consults the preference lists and takes the tool listed as first.  For example, there are several ways to visualize a 3-d polytope: jreality, threejs, povray, etc.  Another example is the convex hull computation for which up to five different algorithms (depending on the coordinate type) come into consideration.  The sensible choice between them can't be made based on some quantitative estimates; instead, your intuition and, sometimes, personal taste must take over the leadership.
-As with custom variables, polymake offers two ways of handling the preferences:
-  - Manually editing the file ''~/.polymake/prefer.pl'' . The preferences are stored in the last section of this file, grouped by applications.  What you see there are exact copies of ''prefer'' commands as they appear in the polymake rules.  Modify them at your taste.  They have the same syntax as the interactive commands described below.
+Preference lists are persisted in your personal settings file ''~/.polymake/settings'' alongside with the custom variables.  They can be manipulated using the following polymake shell commands:
-  -- Calling interactive commands:
+  ? ''%%prefer "label";%%''
-    ? ''%%prefer "label";%%''
+  :: Declare some tool to be the preferred one for any tasks it may perform.  For example, saying ''%%prefer "jreality";%%'' instructs polymake to call jReality to display any kind of 2-d, 3-d, and 4-d drawings related to polytopes, as well as graphs visualized with spring embedding model.  You can specify your wishes more precisely, though: saying ''%%prefer "graphviz.graph";%%'' makes the ''neato'' program from the graphviz package the default tool for visualizing graphs, letting jReality be responsible for all the rest.
-    :: declare some tool to be the preferred one for any tasks it may perform.  For example, saying ''%%prefer "jreality";%%'' instructs polymake to call jReality to display any kind of 2-d, 3-d, and 4-d drawings related to polytopes, as well as graphs visualized with spring embedding model.  You can specify your wishes more precisely, though: saying ''%%prefer "graphviz.graph";%%'' makes the ''neato'' program from the graphviz package the default tool for visualizing graphs, letting jReality be responsible for all the rest.
+  ? ''%%prefer "*.task label1, label2 ...";%%''
-    ? ''%%prefer "*.task label1, label2 ...";%%''
+  :: Establish a specific order of preferred tools for special task.  For example, a command ''%%prefer "*.convex_hull cdd, lrs, beneath_beyond";%%'' directs polymake to always try the cdd convex hull computation first; if it fails, the lrs algorithm will be applied; if both fail, then beneath_beyond, and as the last resort anything else without specific order.
-    :: establish a specific order of preferred tools for special task.  For example, a command ''%%prefer "*.convex_hull cdd, lrs, beneath_beyond";%%'' directs polymake to always try the cdd convex hull computation first; if it fails, the lrs algorithm will be applied; if both fail, then beneath_beyond, and as the last resort anything else without specific order.
+  ? ''%%reset_preference "label";%%''
-    ? ''%%reset_preference "label";%%''
+  :: Restore the preference lists containing the specified label to the pristine state, as it appears in the rule files.  It accepts a tool name or a wildcard expression as its argument and restores the effect of any matching ''prefer'' command encountered in the rule files.  The most radical form ''%%reset_preference "*";%%'' forgets any preferences you've ever changed and restores the "factory settings".
-    :: restore the settings to the pristine state.  It accepts a tool name or a wildcard expression as its argument and restores the effect of any matching ''prefer'' command encountered in the rule files.  The most radical form ''%%reset_preference "*";%%'' forgets any preferences you've ever changed and restores the "factory settings".
+  ? ''%%prefer_now "labels";%%''
-    .. Both commands come immediately into effect; before exiting the interactive session the changes will be stored in your preference file.
+  :: Does the same as ''prefer'', but restores the previous setting as soon as the current input is completely evaluated.  No persistent changes are made.  This command can be seen as the ''local'' modification of ''prefer'' (standard perl does not allow to apply ''local'' to anything but variable assignments).
-    ? ''%%prefer_now "labels";%%''
+  ? ''show_preferences;''
-    :: does the same as ''prefer'', but restores the previous setting as soon as the current input is completely evaluated.  No persistent changes are made.  This command can be seen as the ''local'' modification of ''prefer'' (standard perl does not allow to apply ''local'' to anything but variable assignments).
+  :: Display all active preference lists in the current application.  If you want to find out all tools involved into the preference mechanics, including inactive ones, use the TAB completion in ''prefer'' command or browse the help system starting at the topic '/preferences' .
-    ? ''show_preferences;''
-    :: display all active preferences in the current application.  If you want to find out all tools involved into the preference mechanics, including inactive ones, use the TAB completion in ''prefer'' command or browse the help system starting at the topic '/preferences' .
+**Remark:** the location of the personal setting file can be changed from its default value ''~/.polymake'' by setting an environment variable ''POLYMAKE_USER_DIR=///other/location//'', or overridden temporarily just for one session with a command-line option ''%%--config-path%%''.
-**Remark:** the location of the configuration files can be changed from its default value ''~/.polymake'' by setting an environment variable ''POLYMAKE_USER_DIR=///other/location//'', or overridden temporarily just for one session with a command-line option ''%%--config-path%%''.