Individual Contribution                                  Daniel M. Myers
Internet-Draft                                   Monolithic Technologies
Category: Informational                                        June 2001
Expires: December 2001


                      Procedural Footnote Language
                              Version 1.0
                         draft-myers-pfl-02.txt 


Status of this Memo

   This document is an Internet-Draft and is subject to all provisions
   of Section 10 of RFC2026.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF), its areas, and its working groups.  Note that
   other groups may also distribute working documents as Internet-
   Drafts.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   The list of current Internet-Drafts can be accessed at
      http://www.ietf.org/1id-abstracts.html

   The list of Internet-Drafts Shadow Directories can be accessed at
      http://www.ietf.org/shadow.html

Copyright Notice

   Copyright (C) The Internet Society (2001).

Abstract

   This document sets out the proper syntax and usage of the Procedural
   Footnote Language (PFL) - a system of adding structured footnote
   objects to a text file.

Introduction

   In the course of composing email or other text documents it may be
   desirable to add comments or other notes to clarify a statement when
   those additions may not fit the syntax of the statement, or may not
   significantly add to the reader's understanding of the statement, and
   where the use of a parenthetical comment would adversely affect the
   readability of the statement.  In such a situation footnotes are one
   method of including the additional information with minimal negative
   impact.






Myers                    Monolithic Technologies                [Page 1]


Internet-Draft                   PFL 1.0                    19 June 2001


1. The PFL Document

   A document complying with the PFL 1.0 format consists of plain ASCII
   text and is divided into two sections: the BODY and the FOOTNOTES.


   1.1 The BODY Section

      The BODY section consists of zero or more ASCII characters with an
      undefined structure, and containing zero or more footnote
      delimiters.  A footnote delimiter consists of a positive integer
      enclosed in square brackets.  As the square bracket is used in PFL
      as a delimiter to indicate a footnote, any square brackets in the
      body of a document must be "escaped out" by enclosing them in
      square brackets.  All footnote delimiters in the BODY section must
      have a corresponding footnote in the FOOTNOTE section.

         Example:  This is body text containing a footnote tag[1]

         Example:  [[]This is body text[1] enclosed in square
                   brackets.[]]

      Footnote delimiters may be marked as being "optional" by enclosing
      the number within the square brackets in parentheses.  Note that
      the corresponding footnote in the FOOTNOTE section does not
      contain the parentheses.

         Example:  This is an optional footnote delimiter[(2)].

   1.2 The FOOTNOTES Section

      The FOOTNOTES section consists of the PFL document identifier
      followed by zero or more footnotes in PFL format.  The PFL
      document identifier is the text "PFL" followed by the version
      number, enclosed in square brackets, on a line by itself.  Any
      text between the PFL document identifier and the first PFL
      footnote is ignored.

         Example:  [PFL1.0]

      The proper syntax of a PFL footnote is a number enclosed by square
      brackets followed by a space followed by 1 or more ASCII
      characters.  There must be no text between the start of the line
      and the start of the footnote.  As with the body text any square
      brackets in the text portion of a PFL footnote must be escaped out
      by enclosing them in square brackets.  All footnotes in the
      FOOTNOTE section must have a corresponding delimiter in the BODY
      section.  The numbers of the footnotes in the FOOTNOTES section
      must be in sequential order and may not skip any values.

         Example:  [1] Hi Sherry!



Myers                    Monolithic Technologies                [Page 2]


Internet-Draft                   PFL 1.0                    19 June 2001


      Footnotes may also have one or two optional parameters.  A first
      parameter will indicate the maximum number of times a footnote is
      to be evaluated, with any further delimiters referencing that
      footnote being ignored.

         Example:  The footnote "[1:3] Wubba[1]" would parse as " Wubba
                   Wubba Wubba"

      A second parameter will indicate the minimum index value for the
      footnote to be evaluated.  The footnote will not be evaluated
      before this index is reached.  Note that a delimiter referencing
      the footnote will advance the index for that footnote, but will
      not add to the number of times the footnote has been evaluated
      unless the index is greater or equal to the first parameter

         Example:  The PFL document below ...

                   [1]
                   [PFL1.0]
                   [1:2] Hi ho![1][2]
                   [2:1:2] It's off to work we go!
                   [PFLEND]

         would evaluate to "Hi ho! Hi ho! It's off to work we go!"

      The minimal allowed document in PFL format would be:

                   [PFL1.0]

      The traditional "Hello World" program would be represented in
      PFL as:

                   [1]
                   [PFL1.0]
                   [1] Hello World
                   [PFLEND]

2. Markers

   There are a number of optional markers.  These markers all take the
   form of one or more ASCII characters enclosed in square brackets.

   [HS] (honorable salutation) - This marker may occur in either the
      BODY or FOOTNOTES sections of a PFL document and is the equivalent
      to a delimiter pointing to a footnote that contains the text "Hi
      Sherry!".  Note that if the [HS] marker appears at the start of a
      line in the FOOTNOTES section, it is taken as a special "Hi
      Sherry!" footnote and will generate a UFA error if a [HS] marker
      does not also appear elsewhere in the document.

   [PFLEND] (PFL End of Document) - Indicates the end of the FOOTNOTES
      section of a PFL document.  This marker may only be used at the


Myers                    Monolithic Technologies                [Page 3]


Internet-Draft                   PFL 1.0                    19 June 2001


      end of the FOOTNOTES section.  All text in a document after
      the [PFLEND] marker will be ignored.

   [[] ("Escaped" Leading Square Bracket) - used when a open square
      bracket is desired anywhere in the document.  This marker may not
      be used at the start of a line in the FOOTNOTES section of a
      document.

   []] ("Escaped" Trailing Square Bracket) - used when a close square
      bracket is desired anywhere in the document.  This marker may not
      be used at the start of a line in the FOOTNOTES section of a
      document.

3. Functions

   PFL Defines a number of built in functions of a mathematical or
   logical nature.  Each function is evaluated by the parser.  The
   functions may be nested as required. Parameters enclosed in angle
   brackets are optional.

   [ABC] - returns ABCDEFGHIJKLMNOPQRSTUVWXYZ

   [ADD:x:y] - returns the value x + y

   [AND:condition 1:condition 2] - returns true if both conditions are
      true, and false otherwise

   [ASCII:hex] - returns the ASCII character for a given hexadecimal
      value

   [BEEP] - system beep

   [DATE] - returns the current date

   [FALSE] - returns false

   [GT:x:y] - returns true if x is greater than y, and false otherwise

   [HEX:character] - returns the hexadecimal value of an ASCII character

   [IF:condition:x<:y>] - Evaluates the condition and branches to
      footnote x if the result is true, otherwise branches to footnote
      y.  A footnote used as the condition will always evaluate as true.

   [INDEX:x] - returns the number of times that footnote x has been
      evaluated by the parser

   [IS:x:y] - returns true if x is equal to y, and false otherwise

   [LEN:text1] - returns the number of characters in text1

   [LT:x:y] - returns true if x is less than y, and false otherwise


Myers                    Monolithic Technologies                [Page 4]


Internet-Draft                   PFL 1.0                    19 June 2001


   [NOT:condition] - returns true if the condition is false, and false
      otherwise

   [OR:condition 1:condition 2] - returns true if either condition is
      true (or both), and false otherwise

   [ORD:x] - returns the ordinal value of x (i.e. "first" for "1",
      "second" for "2", etc...)

   [RET] - returns a carriage return

   [SPACE] - returns a space

   [SUB:x:y] - returns the value x - y

   [TAB] - returns a tab

   [TIME] - returns the current time

   [TRUE] - returns true

   [USERDATA<:parameter>] - returns various data on the user, if it is
      available.  If the parameter is omitted then it will return true
      if the user data is available, and false otherwise.

      [USERDATA:FULLNAME] - returns the full name of the user in the
         format "firstname lastname"

      [USERDATA:FIRSTNAME] - returns the first name of the user

      [USERDATA:LASTNAME] - returns the last name of the user

      [USERDATA:INITIAL] - returns the middle initial of the user

      [USERDATA:COMPANY] - returns the company name of the user

      [USERDATA:STREET] - returns the street address of the user

      [USERDATA:CITY] - returns the city of the user

      [USERDATA:REGION] - returns the region of the user

      [USERDATA:POSTAL] - returns the postal zone of the user

      [USERDATA:COUNTRY] - returns the country of the user

      [USERDATA:LANGUAGE] - returns the preferred language of the user

   [VER] - returns the PFL version of the parser

   [XOR:condition 1:condition 2] - returns true if either condition is
      true (but not both) , and false otherwise


Myers                    Monolithic Technologies                [Page 5]


Internet-Draft                   PFL 1.0                    19 June 2001


   [ZEN] - doesn't return anything

4. Possible Errors

   The following are potential errors that may be encountered when
   parsing a PFL document.

   FSE - Footnote Sequence Error:  The footnote numbers in the FOOTNOTES
         section are not in sequential order.

   IFA - Improper Footnote Alert:  A footnote was found in the FOOTNOTES
         section that was not properly formed.

   MDA - Malformed Delimiter Alert:  A delimiter was found in either the
         BODY or the FOOTNOTES section that was not properly formed.
         This may be caused by square brackets that have not been
         properly escaped.

   MFA - Missing Footnote Alert:  There is a delimiter in the BODY
         section of the document that has no corresponding footnote in
         the FOOTNOTES section.

   NOT - Not a PFL Document:  No PFL document identifier was found.

   TMI - Too Much Information:  There was a buffer overflow while
         parsing the document, possibly due to a circular reference.

   UFA - Unassigned Footnote Alert:  There is a footnote in the
         FOOTNOTES section of the document that has no corresponding
         delimiter in the BODY section.

   UPM - Unexpected PFLEND Marker:  A [PFLEND] marker was encountered in
         the BODY section of the document.

   UVN - Unrecognized Version Number:  The version of PFL specified in
         the PFL document identifier was not recognized by the parser.

5. Security Considerations

   This document raises no security issues.

6. Author's Address

   Daniel Myers
   PO Box 523
   Loveland, OH 45140-0523

   Phone: +1 513-708-1024
   Email: myers@monogames.com





Myers                    Monolithic Technologies                [Page 6]


Internet-Draft                   PFL 1.0                    19 June 2001


7. Full Copyright Statement

   Copyright (C) The Internet Society (2001).  All Rights Reserved

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or any
   other Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than
   English.

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.

   This document and the information contained herein is provided on an
   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.



























Myers                    Monolithic Technologies                [Page 7]