Backporting POD and tests for Menu.pm from trunk

git-svn-id: https://ledger-smb.svn.sourceforge.net/svnroot/ledger-smb/branches/1.2@1387 4979c152-3d1c-0410-bac9-87ea11338e46

1 files changed, 109 insertions, 34 deletions

diff --git a/LedgerSMB/Inifile.pm b/LedgerSMB/Inifile.pm
index 1b89502c..97c1a7ff 100755
--- a/LedgerSMB/Inifile.pm
+++ b/LedgerSMB/Inifile.pm
@@ -1,37 +1,112 @@
-#=====================================================================
-# LedgerSMB
-# Small Medium Business Accounting software
-# http://www.ledgersmb.org/
-#
-# Copyright (C) 2006
-# This work contains copyrighted information from a number of sources all used
-# with permission.
-#
-# This file contains source code included with or based on SQL-Ledger which
-# is Copyright Dieter Simader and DWS Systems Inc. 2000-2005 and licensed
-# under the GNU General Public License version 2 or, at your option, any later
-# version.  For a full list including contact information of contributors,
-# maintainers, and copyright holders, see the CONTRIBUTORS file.
-#
-# Original Copyright Notice from SQL-Ledger 2.6.17 (before the fork):
-# Copyright (C) 2002
-#
-#  Author: DWS Systems Inc.
-#     Web: http://www.sql-ledger.org
-#
-#  Contributors:
-#   Tony Fraser <tony@sybaspace.com>
-#
-#======================================================================
-#
-# This file has undergone whitespace cleanup.
-#
-#======================================================================
-#
-# routines to retrieve / manipulate win ini style files
-# ORDER is used to keep the elements in the order they appear in .ini
-#
-#=====================================================================
+
+=head1 NAME
+
+Inifile  Routines to load LedgerSMB menu files.
+
+=head1 STATUS
+
+API I<deprecated>, removed in 1.3.
+
+=head1 SYNOPSIS
+
+Routines to load LedgerSMB menu files.  LedgerSMB menu files are a specific 
+form of ini file.
+
+Files use both ';' and '#' to denote line comments.  Any text after a line that
+starts with '.' (i.e. ".foo") is ignored.  Menu items are denoted as [section],
+with the sections containing key=value pairs.  The keys 'module', 'action', 
+'target', 'href', and 'submenu' are specially treated, while other keys are
+output as arguments to the destination link.  Blank lines are ignored.
+
+=head2 Special key treatment
+
+=over
+
+=item action
+
+This key is deleted on menuitem calls if there is no href value.
+
+=item module
+
+This is the Perl script that the menu item will call if the href attribute is
+not set.  This key is always deleted on a menuitem call.
+
+=item target
+
+The value given for target will be passed as the target attribute for the tag.
+This key is always deleted on a menuitem call.
+
+=item href
+
+When set, this key's value becomes the base URL for the menu item.  This key is
+always deleted on a menuitem call.
+
+=item submenu
+
+This key is not displayed in output, but is deleted from the Menufile object
+when menuitem is called on the item.
+
+=back
+
+=head2 Value Interpolation
+
+If a value for a regular key includes an equals sign (=), values from the user's
+configuration are substituted into the place of the string preceding and the 
+first encountered equals sign in the value.  So a menu entry of 'apples=login='
+would have the substition of 'apples=$myconfig->{login}' on generation of the
+menu link.
+
+=head1 METHODS
+
+=over
+
+=item new ([$filename])
+
+Create a new Menufile object.  If a filename is specified, load the file with
+add_file.
+
+=item add_file ($filename)
+
+Load the contents of the specified file into the Menufile object.  If the file
+cannot be read, Form->error will be called with the failure message.  Attempts
+to load already loaded items will result in the newer item merging with and 
+overwriting stored data from the previous load.
+
+Menu item titles are stored as keys in the Menufile object, and a special key, 
+ORDER maintains a list of the order in which menu items were first seen.
+
+=back
+
+=head1 Copyright (C) 2006, The LedgerSMB core team.
+
+ #====================================================================
+ # LedgerSMB
+ # Small Medium Business Accounting software
+ # http://www.ledgersmb.org/
+ #
+ # Copyright (C) 2006
+ # This work contains copyrighted information from a number of sources 
+ # all used with permission.
+ #
+ # This file contains source code included with or based on SQL-Ledger
+ # which is Copyright Dieter Simader and DWS Systems Inc. 2000-2005
+ # and licensed under the GNU General Public License version 2 or, at
+ # your option, any later version.  For a full list including contact
+ # information of contributors, maintainers, and copyright holders,
+ # see the CONTRIBUTORS file.
+ #
+ # Original Copyright Notice from SQL-Ledger 2.6.17 (before the fork):
+ # Copyright (C) 2002
+ #
+ #  Author: DWS Systems Inc.
+ #     Web: http://www.sql-ledger.org
+ #
+ #  Contributors:
+ #   Tony Fraser <tony@sybaspace.com>
+ #
+ #=====================================================================
+
+=cut
 
 package Inifile;