#  Copyright (c) 1997-2010
#  Ewgenij Gawrilow, Michael Joswig (Technische Universitaet Darmstadt, Germany)
#  http://www.polymake.de
#
#  This program is free software; you can redistribute it and/or modify it
#  under the terms of the GNU General Public License as published by the
#  Free Software Foundation; either version 2, or (at your option) any
#  later version: http://www.gnu.org/licenses/gpl.txt.
#
#  This program is distributed in the hope that it will be useful,
#  but WITHOUT ANY WARRANTY; without even the implied warranty of
#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#  GNU General Public License for more details.
#-------------------------------------------------------------------------------
#  $Project: polymake $$Id: help.rules 9570 2010-03-15 23:21:23Z gawrilow $

# @topic top
# You are in the interactive mode of polymake.
#
# You may type in any valid perl expression, it will be evaluated as soon as it is complete,
# that is, terminated with a semicolon.  Longer constructs (if-else-clauses, loops,
# long lists, etc.) can be continued on several lines; continuation lines are marked
# with ordinal numbers in parentheses.  Typing Control-C amidst such a block quits without
# execution.
#
# The input prompt shows the name of the currently active application.
# To change to another application, type:   application "NAME";
#
# All command line editing features of GNU Readline library are available,
# including history search, key bindings defined in ~/.inputrc, etc.
# Please refer to the documentation shipped with Readline for details.
#
# TAB completion tries to guess the context and to present suitable alternatives.
# When used in complex expressions, it can, however, make some invalid suggestions;
# please be careful.
#
# Variables can be introduced like this: 'declare $x;' or 'declare $x=1;'
# or simply via first assignment: '$x=1;'
# 'my' variables should be used with caution, as their life scope is limited
# to the current expression.  
#
# Here are some help topics for the beginners:
# help 'functions/Basic';
#    An overview of the most useful commands.
# help 'help';
#    How to navigate in the help system.
# help 'credits';
#    List of references to third-party software bundled with or interfaced
#    through the current application.
# help '/';
#    Describe the current application and list all subtopics in the help tree.
# help 'citation';
#    How to cite polymake correctly.
#
# Press F1 to get context-sensitive help to the keyword under cursor.


# @topic functions/Basic
# These functions are part of the core user interface.
# They are available in both scripting and interactive modes.

# @topic functions/Interactive
# These functions are available in the interactive shell only.

# @topic functions/application
# @category Basic
#
# Called in void context sets the current application to the one given by //name//
# (loading its rules if necessary) or by an object of type ''Polymake::Core::Application''.
#
# Called in non-void context loads the application if necessary and returns the ''Application''
# object representing it, but does not make it the current application.
#
# Finally, if called without arguments, just returns the current ''Application'' object,
# which is also always available in the variable ''$application''.
# Say ''print $application->name;'' to see its name.
#
# @param String name | Application app_obj


# @topic functions/include
# @category Basic
# Read additional rule files, interpret them in the context of the current application.
# The rule files may reside in the application's standard subdirectory ''rules'' or in any
# of the known extensions.
# @param String rulefile : one or more filenames.


# @topic functions/load
# @category Basic
# Read the object data file.
# If the data file is in old plain ASCII format and does not contain a type declaration,
# the default type of the current application is assumed.
# @param String filename
# @return Object


# @topic functions/save (Object;$)
# @category Basic
#
# Store the given //object// in a data file.
#
# If //filename// is specified, create the file with this name (or overwrite an existing one)
# and store the object there.
#
# If //filename// is omitted, write the object back to the file it was loaded from.
# If the object is not yet associated with a file (e.g. it was created with a ''new'' constructor)
# a new file is created, with the name consisting of the object name and the application-specific suffix.
# If the object name is empty, you will be asked for it.  In non-interactive mode an artificial name
# of the form ''ObjectType_NNN'' will be generated, where ''NNN'' is an ordinal number.
#
# The save operation is only performed if the boolean attribute ''object->changed'' has the true vakue.
# @param Object object
# @param String filename


# @topic functions/load_data
# @category Basic
#
# Read the data file created earlier by [[save_data]] and return the data object stored there.
# @param String filename
# @return any data object; in list context additionally returns the optional description read from in the file.


# @topic functions/save_data ($$;$)
# @category Basic
#
# Create an XML data file and store the given data object there, together with an optional description.
# Only objects of complex types declared as ''property_type'' can be stored this way.
# @param any data object
# @param String filename
# @param String description


# @topic functions/prefer
# @category Basic
#
# Make the production rules, user functions, or methods (further called //items//)
# matching the given //label_expression// be preferred over competing rules (functions, methods).
#
# The new preference list is also saved in your personal file ''~/.polymake/prefer.pl''
# It remains active in all forthcoming sessions until you revoke it with another
# //prefer// or [[reset_preference]] command.
#
# For the sake of symmetry you can call this function by its alias name //set_preference//.
#
# @param String label_expression : may have one of the following forms:
#
#   "top_label" or "top_label.sublevels" selects all items whose labels start with the given path,
#   e.g. "javaview" or "cdd.convex_hull"
#
#   "*.sublevels", "top_label_1", "top_label_2", ... selects all items with matching labels and
#   establishes a ranking between them.


# @topic functions/prefer_now
# @category Basic
#
# The same as [[prefer]], but does not store the changes persistently.  The lifespan of the
# new preference order lasts up to the end of the current user cycle
# (that is, end of user script or interpretation of the current input line in interactive mode).
# @param String label_expression


# @topic functions/reset_preference
# @category Basic
#
# Reset the matching preference lists to the initial state as declared in the rule files.
# This change is permanent, the former settings are wiped out from your preference file
# ''~/.polymake/prefer.pl''
#
# @param String label_expression : "label" or "label.sublevels" or "*.sublevels" or "*" or "all"
#   Two last forms effects all preference lists in all loaded applications.


# @topic functions/set_custom
# @category Basic
#
# Set the custom variable, array, hash, or hash element to a new value and store it perpetually
# in your personal settings file ''~/.polymake/customize.pl''
#
# @param any assignment : following expressions are allowed:
#  ''$var=value;''
#  ''@array=(values);''
#  ''%hash=( key => value, ... );''
#  ''$hash{key}=value;''


# @topic functions/reset_custom
# @category Basic
#
# Reset the custom variable, array, hash, or hash element to the default value(s) as defined in the rule base
# and store it perpetually in your personal settings file ''~/.polymake/customize.pl''
# @param any Variable : following expressions are allowed:
#  ''$var;''
#  ''@array;''
#  ''%hash;''
#  ''$hash{key};''



# @topic functions/help
# @category Interactive
#
# Display the help information or comments associated with a given item.
#
# If a single word without path separators ''/'' is given, it is looked for
# in the entire help hierarchy.
# If there are more than 5 matches, the corresponding help commands with full paths
# are generated and placed into the shell history buffer, so you can choose the themes
# of interest using the standard history navigation (arrow up/down keys).
#
# You may use TAB completion to navigate thru the category tree.
# Start with '/' to see the description of the current application.
# Descend via 'functions', 'objects', 'types', or 'preferences' to the topics
# of interest.  If you stop in an intermediate category level, both the comment
# specific to this category and the list of subtopics will be displayed.
# @param String item : "word" | "category/subcategory/.../item"


# @topic functions/apropos
# @category Interactive
#
# List all help topics matching the given pattern.  bash-like syntax for wildcards is supported.
# @param String pattern


# @topic functions/history
# @category Interactive
#
# Let you choose and edit the commands typed earlier in the interactive shell.
# The complete history list is written in a temporary file, which is opened with a text editor.
# Until you store your favorite editor in the custom variable ''$history_editor'',
# the values of environment variables ''VISUAL'' and ''EDITOR'' are consulted.


# @topic functions/replay_history
# @category Interactive
#
# Bring the interactive shell in the replay mode.  In this mode you can revisit, edit and execute the commands stored in the history.
# Simply press RETURN if you want to execute the command as is; alternatively you can edit it or jump over it using the
# usual history navigation keystrokes.  The replay mode is switched off when the last history line has been executed or navigated over.
# You can leave it prematurely by entering Control-C as well.
# The replay mode is visually signaled by the history line number in square brackets displayed in the shell prompt.


# @topic functions/load_commands
# @category Interactive
#
# Read the lines from the given file, filter out comments and empty lines, append them to the
# history list of the interactive shell, and enter the replay mode (see [[replay_history]]) starting
# at the first inserted line.
# @param String filename


# @topic functions/script ($@)
# @category Basic
#
# Run the polymake script, passing the arguments in ''@ARGV''.
# The scripts specified without path are first looked for in the current application's ''scripts'' subdirectory,
# then in the user's script directories (custom array ''@lookup_scripts''), and finally in the
# top-level ''scripts'' subdirectory.
# @param String filename : script code
# @param any Arguments : arbitrary many arguments passed to the script


# @topic functions/found_extension (;$)
# @category Interactive
#
# Found the extension for the current application rooted at the given directory.  The ''apps'' and ''build'' subtrees
# are created unterneath if necessary.  If it's the first application being created or extended there, the //path// will be inserted
# in the custom list ''@lookup_applications''.
# @param String path : top-level directory of the extension.
#   By default, the first writeable directory listed in ''@lookup_applications'' will be taken.


# @topic functions/found_application ($;$)
# @category Interactive
#
# Create a directory tree for a new application, rooted at the given extension.  The ''apps'' and ''build'' subtrees
# are created unterneath if necessary.  If it's the first application being created or extended there, the //path// will be inserted
# in the custom list ''@lookup_applications''.
#
# The new application is neither loaded at this moment, nor it is inserted in the ''@start_applications'' list.
# Both must be done manually at the appropriate time.
#
# @param String name : new application's name
# @param String path : top-level directory of the new or existing extension.
#   By default, the first writeable directory listed in ''@lookup_applications'' will be taken.


# @topic functions/import_extension
# @category Interactive
# Load the extension installed in the given directory. The //path// is also included in the custom list ''@lookup_applications''
# for future sessions.
# @param String path : top-level directory of the extension.


# @topic citation
#
# If you are using polymake, please, cite:
#
# @incollection{polymake,
#  author =       {Ewgenij Gawrilow and Michael Joswig},
#  title =        {polymake: a Framework for Analyzing Convex Polytopes},
#  pages =        {43-74},
#  editor =       {Gil Kalai and G\"unter M. Ziegler},
#  booktitle =    {Polytopes --- Combinatorics and Computation},
#  publisher =    {Birkh\"auser},
#  year =         {2000}
# }


# Local Variables:
# mode: perl
# c-basic-offset:3
# End:
