home | help 
ptop.cfg(5)	       ptop source beautifier config file	     ptop.cfg(5)

NAME
     ptop.cfg - The ptop source-beautifier configuration file.

     ptop is the source beautifier of the FreePascal project.

     Origin probably Pascal-TO-Pascal.cfg

DESCRIPTION
     This is the main configuration file of the ptop FPC source beautifier

     The  configuration  file for ptop(1) isn't necessarily called ptop.cfg, and
     is also not auto-loaded, so the name doesn't matter much. This man-page de-
     scribes the structure of such a configuration file for ptop(1)

STRUCTURE
     The structure of a ptop configuration file is a simple building  block  re-
     peated  several  (60-70)  times,  once for each pascal keyword known to the
     ptop program. (see the default configuration file	or  ptopu.pp  source  to
     find out which keywords are known)

     The basic building block of the configuration file consists out of one, two
     or  three	lines,	describing  how  ptop should react on a certain keyword.
     First a line without square brackets with the following format:

     keyword=option1,option2,option3,...

     If one of the options is "dindonkey" (see further	below),  a  second  line
     (with square brackets) is needed like this:

     [keyword]=otherkeyword1,otherkeyword2,otherkeyword3,...

     Then  if one of the options is "gobsym", a third line (with angle brackets)
     is needed like this:

     <keyword>=terminalword1,terminalword2,terminalword3,...

     As you can see the block contains two types of  identifiers,  keywords(key-
     word,  otherkeyword1..3  and terminalword1..3 in the above example) and op-
     tions, (option1..3 above).

     Keywords are the built-in valid Pascal  structure-identifiers  like  BEGIN,
     END,  CASE,  IF, THEN, ELSE, IMPLEMENTATION. The default configuration file
     lists most of these.

     Besides the real Pascal keywords, some other codewords are used for  opera-
     tors and comment expressions. These are listed in the following table:

     Name of codeword	      operator
     -------------	      -----
     casevar		      : in a case label (<>'colon')
     becomes		      :=
     delphicomment	      //
     opencomment	      { or (*
     closecomment	      } or *)
     semicolon		      ;
     colon		      :
     equals		      =
     openparen		      [
     closeparen 	      ]
     period		      .

     The  Options  codewords  define actions to be taken when the keyword before
     the equal sign is found.

     Option		 does what
     -------		 ---------
     crsupp		 suppress CR before the keyword.
     crbefore		 force CR before keyword
			 (doesn't go with crsupp :) )
     blinbefore 	 blank line before keyword.
     dindonkey		 de-indent on associated keywords (see below)
     dindent		 de-indent (always)
     spbef		 space before
     spaft		 space after
     gobsym		 Print symbols which follow a keyword,
			 but which do not affect layout.
			 Prints until terminators occur.
     inbytab		 indent by tab.
     crafter		 force CR after keyword.
     upper		 prints keyword all uppercase
     lower		 prints keyword all lowercase
     capital		 capitalizes keyword: 1st letter
			 uppercase, rest lowercase.

     The option "dindonkey" requires some extra parameters, which are set  by  a
     second  line  for that keyword (the one with the square brackets), which is
     therefore only needed if the options contain "dinkdonkey"	(contraction  of
     de-indent on assiociated keyword).

     "dinkdonkey"  deindents  if  any of the keywords specified by the extra op-
     tions of the square-bracket line is found.

     In a similar manner the option "gobsym", short for gobble symbols, requires
     some additional information in order to perform its function. The	"gobsym"
     option  indicates	that  all symbols following the keyword should be passed
     through unchanged until a terminal symbol is reached. The list  of  accept-
     able termial symbols is provided by the angle-bracket line.

EXAMPLES
     The block

     else=crbefore,dindonkey,inbytab,upper
     [else]=if,then,else

     Means:

     The  keyword  this  is  about is else , it's on the LEFT side of both equal
     signs.

     When the ptop parser finds ELSE, the options tell it to  do  the  following
     things:

     - (crbefore) Don't allow other code on the line before
	the keyword. (ELSE alone on a line)
     - (dindonkey) De-indent on the keywords
	in square brackets line (if,then,else)
     - (inbytab) indent by tab.
     - (upper) uppercase the keyword (ELSE)

     The block

     case=spaft,gobsym,inbytab,crafter,capital
     <case>=ofsym

     Means:

     The  keyword  this  is  about is case , it's on the LEFT side of both equal
     signs.

     When case is found, the options tell it to do the following things:

     - (spaft) Insure that there is a space
	after the keyword. (case)
     - (gobsym) pass symbols through unchanced until one of
	the words in the angle brackets line (of) is found.
     - (crafter) Make sure terminator (of) ends the line.
     - (inbytab) indent by tab.
     - (capital) Capitalize the keyword (case becomes Case).

     Try to play with the configfile until you find the effect you  desire.  The
     configurability and possibilities of ptop are quite large compared to other
     shareware source beautifiers found on e.g. SIMTEL.

ACKNOWLEDGEMENTS
     The  writer  of  the  program, Michael van Canneyt, who also helped out ex-
     plaining the format of ptop.cfg.

     Questions/corrections can be mailed to fpc-devel@vekoll.saturnus.vein.hu

     Also thanks to the rest of the FPC development team.

SEE ALSO
     ptop binary
	    ptop(1)

     Compiler
	    ppc386(1)

     Other FPC utils
	    ppdep(1) ppudump(1) ppumove(1) h2pas(1)

FreePascal			 25 January 2007		     ptop.cfg(5)
home | help