home *** CD-ROM | disk | FTP | other *** search
/ Chip 2005 February / CMCD0205.ISO / Software / Freeware / Programare / highlight / highlight-W32GUI-2.2-6-Setup.exe / embedded / InfoAfter.txt < prev    next >
Text File  |  2004-12-08  |  12KB  |  365 lines
  1. --------------------------------------------------------------------------------
  2. ---  HIGHLIGHT MANUAL (W32 GUI) - Version 2.2-6 -------------- NOVEMBER 2004 ---
  3. --------------------------------------------------------------------------------
  4.  
  5. OSI Certified Open Source Software
  6.  
  7.  
  8. Highlight converts sourcecode to HTML, XHTML, RTF, LaTeX, TeX or XSL-FO files
  9. with syntax highlighting. Its language definitions, colour themes and
  10. indentation schemes are customizable.
  11.  
  12.  
  13. CONTENT:
  14. --------------------------------------------------------------------------------
  15.  
  16. 1. Platforms
  17. 2. Supported programming/markup languages
  18. 3. Features
  19. 4. Highlight file format
  20. 5. Defining new language definitions
  21. 6. Defining new colour themes
  22. 7. Defining new indentation schemes
  23. 8. Windows Explorer integration
  24. 9. Contact
  25.  
  26.  
  27. 1. PLATFORMS:
  28. --------------------------------------------------------------------------------
  29.  
  30. Highlight is written in C++. There exist three versions of Highlight:
  31. - UNIX console application
  32. - Win32 console application
  33. - Win32 GUI application
  34.  
  35. For other platforms, see the highlight homepage. The source package is known to
  36. compile with gcc3.x, MS Visual .NET, and MW Codewarrior 8.
  37.  
  38.  
  39. 2. SUPPORTED PROGRAMMING / MARKUP LANGUAGES:
  40. --------------------------------------------------------------------------------
  41.  
  42. Currently, Highlight supports the following programming languages, markup
  43. languages and configuration files:
  44.  
  45. Action Script, ADA 95, Agda, AMPL, ASP, Aspect, Assembler, Amtrix, Avenue,
  46. (G)AWK, Bash, BlitzBasic, BibTex, BMS, C, C++, C#, ClearBasic, Clipper, Cobol,
  47. Coldfusion MX, CSS, DOS-Batch, Eiffel, Erlang, Euphoria, Express, Felix, Fortran,
  48. Frink, Haskell, HTML, httpd.conf, Icon, IDL, INI, IO, Jasmin, Java, JavaScript,
  49. JSP, LaTeX, LDIF,Lisp, Lotos, Lotus Script, Lua, Make, Maya, Matlab, Maple,
  50. Modelica, Modula 3, Nasal, OCaml, (Object) Pascal, Objective C, Paradox, PATROL,
  51. Perl, PHP, Pike, PL/1, PL/SQL, PostScript, POV Ray, Progress, Prolog, Python,
  52. Relax NG Compact, Rexx, RPM Spec, Ruby, Small, SML, Spin, Squirrel, SuperX++,
  53. Sybase, VHDL, Visual Basic, XML.
  54.  
  55.  
  56. 3. FEATURES:
  57. --------------------------------------------------------------------------------
  58.  
  59. - highlighting of keywords, types, strings, numbers, escape sequences, comments,
  60.   symbols and directive lines
  61. - highlighting of custom keyword classes
  62. - coloured output in HTML, XHTML 1.1, RTF, TeX, LaTeX or XSL-FO format
  63. - customizable reformatting and indentation of C, C++, C# and Java source code
  64. - wrapping of long lines
  65. - output of line numbers
  66. - choice to embed the CSS-definitions in the output (X)HTML file or to save them
  67.   in a separate CSS-file
  68. - 50 colour themes
  69. - recursive batch processing of directories
  70. - conversion of plain text to a given output format without highlighting
  71.  
  72.  
  73. 4. HIGHLIGHT FILE FORMAT
  74. --------------------------------------------------------------------------------
  75.  
  76. All Highlight configuration files are stored in plain ASCII text files. The
  77. format is simple:
  78.  
  79. $ParamName=ParamValue
  80.  
  81. ParamName is the identifier of the parameter, ParamValue is its value.
  82. The parameter names are not case sensitive.
  83. The value may be a single character or a list of words. Lists may be split in
  84. multiple lines.
  85.  
  86. Comments start with # as the first character in a line.
  87.  
  88.  
  89. 5. DEFINING NEW LANGUAGE DEFINITIONS:
  90. --------------------------------------------------------------------------------
  91.  
  92. A language definition is a text file, where keywords and symbols of a program-
  93. ming language are assigned to several categories.
  94. Save the new file in the highlight directory/langDefs* with the following name:
  95.  
  96. <usual extension of sourcecode files>.lang
  97.  
  98. Examples: PHP -> php.lang, Java -> java.lang
  99.  
  100. If there exist multiple suffixes, list them in extensions.conf*.
  101.  
  102. FILE FORMAT:
  103.  
  104. # List of keywords; <class> is the name of the keyword class
  105. # The class must be defined in the applied colour theme to provide a matching
  106. # highlighting style
  107. $KW_LIST(<class>)=<List>
  108.  
  109. # Prefix which determines keywords
  110. # The class must be defined in the applied colour theme to provide a matching
  111. # highlighting style
  112. $KW_PREFIX(<class>)=<Character>
  113.  
  114. # Delimiters for keywords
  115. # The class must be defined in the applied colour theme to provide a matching
  116. # highlighting style
  117. $KW_DELIM(<class>)=<open close>
  118.  
  119. # Tag open and close delimiters
  120. # Tags are formatted like keywords of specified class
  121. $TAG_DELIM(<class>)=<tag_open tag_close>
  122.  
  123. # List of String delimiters
  124. $STRINGDELIMITERS=<List>
  125.  
  126. # List of escape characters in Strings (ie. "\")
  127. $ESCCHAR=<List>
  128.  
  129. # Prefix which disables highlighting of escape characters
  130. # within the following string
  131. $RAWSTRINGPREFIX=<Character>
  132.  
  133. # Delimiters of multi-line comments
  134. $ML_COMMENT=<comment_begin comment_close>
  135.  
  136. # List of strings which start single line comments
  137. $SL_COMMENT=<List>
  138.  
  139. # Set true if single line comments have to start in first coloumn
  140. $FL_COMMENT=<true / false>
  141.  
  142. # Opening string of preprocessor directive lines
  143. $DIRECTIVE=<prefix>
  144.  
  145. # Set true if language source code may be reformatted (only C-style languages!)
  146. $REFORMATTING=<true / false>
  147.  
  148. # Symbols which should be coloured (brackets, operators  etc)
  149. $SYMBOLS=<List>
  150.  
  151. # List of special characters which may occour in keywords
  152. $ALLOWEDCHARS=<character list>
  153.  
  154. # Set to true if multiple line comments may be nested
  155. $ALLOWNESTEDCOMMENTS=false
  156.  
  157. # Set to true if programming language is not case sensitive
  158. $IGNORECASE=<true / false>
  159.  
  160. # Include another language definition stored in the same data directory
  161. $INCLUDE=<language definition>
  162.  
  163.  
  164. Example:
  165.  
  166. #Content of pas.lang (Pascal/Objekt Pascal)
  167.  
  168. $KW_LIST(kwa)=true false if else then nil maxint case goto label and div downto in
  169. mod not of or packed with do for do repeat while to until procedure function
  170. program begin end const var type unit interface implementation uses private
  171. public
  172.  
  173. $KW_LIST(kwb)=array boolean char integer file pointer real set string text record
  174.  
  175. $STRINGDELIMITERS=" '
  176. $SL_COMMENT=//
  177. $ML_COMMENT={ }
  178. $IGNORECASE=true
  179.  
  180. HINT: If you do not want to save new language definitions in the default
  181.       installation directory, you can pass highlight another search path with
  182.       the --add-data-dir option.
  183.  
  184.  
  185. 6. DEFINING NEW THEME DEFINITIONS
  186. --------------------------------------------------------------------------------
  187.  
  188. Colour themes are stored in plain ASCII files, defining the formatting of the
  189. output. The RTF output ignores the background colour attribute. The files have
  190. to be stored as *.style in the highlight directory/themes*. You can apply a
  191. style with the -s option.
  192.  
  193. FILE FORMAT:
  194.  
  195. #<ColourAttr> = RR GG BB
  196. #RR GG BB describes the red/green/blue hex-values which define the colour.
  197. #(Value range: 00 (none) - FF (full))
  198.  
  199. #<FormatAttr> = <bold> <italic> <underline>
  200. #Bold, italic und underline are optional attributes and may be combined.
  201.  
  202.  
  203. # Colour of unrecognized text
  204. $DEFAULTCOLOUR=RR GG BB
  205.  
  206. # Background colour (ignored by RTF)
  207. $BGCOLOUR=RR GG BB
  208.  
  209. # Font size
  210. $FONTSIZE=<number>
  211.  
  212. # Formatting of keywords, which belong to the corresponding keyword class
  213. $KW_CLASS(<class>)=<ColourAttr> ( <FormatAttr> )
  214.  
  215. # Formatting of numbers
  216. $NUMBER=<ColourAttr> ( <FormatAttr> )
  217.  
  218. # Formatting of escape characters
  219. $ESCAPECHAR=<ColourAttr> ( <FormatAttr> )
  220.  
  221. # Formatting of strings
  222. $STRING=<ColourAttr> ( <FormatAttr> )
  223.  
  224. # Formatting of strings within compiler directives
  225. $STRING_DIRECTIVE=<ColourAttr> ( <FormatAttr> )
  226.  
  227. # Formatting of comments
  228. $COMMENT=<ColourAttr> ( <FormatAttr> )
  229.  
  230. # Formatting of single line comments
  231. $SL-COMMENT=<ColourAttr> ( <FormatAttr> )
  232.  
  233. # Formatting of compiler directives
  234. $DIRECTIVE=<ColourAttr> ( <FormatAttr> )
  235.  
  236. # Formatting of symbols (optional, equals to $DEFAULTCOLOUR if omitted)
  237. $SYMBOL=<ColourAttr> ( <FormatAttr> )
  238.  
  239. # Formatting of line numbers
  240. $LINE=<ColourAttr> ( <FormatAttr> )
  241.  
  242.  
  243. Example:
  244.  
  245. # Golden.style
  246. $DEFAULTCOLOUR=dd bb 00
  247. $BGCOLOUR=00 00 00
  248. $FONTSIZE=10
  249. $KW_CLASS(kwa)=dd bb 00 bold
  250. $KW_CLASS(kwb)=dd bb 00
  251. $NUMBER=ff ff ff
  252. $ESCAPECHAR=ff 00 00
  253. $STRING=ff 00 00
  254. $STRING_DIRECTIVE=ff 00 00
  255. $COMMENT=97 83 45 italic
  256. $DIRECTIVE=ff dd aa
  257. $LINE=97 83 45
  258.  
  259.  
  260. 7.  DEFINING NEW INDENTATION SCHEMES
  261. --------------------------------------------------------------------------------
  262.  
  263. You can define custom indentation and formatting schemes. To enable reformatting
  264. for your programming language, a $REFORMATTING=true switch has to be added to
  265. the language definition. Note that the Artistic Style parser was designed to
  266. only handle C-style languages (C++, Java, C#) correctly.
  267. Indentation schemes are stored as *.indent in the highlight dir/indentSchemes*.
  268. Apply your scheme with the option --format-style.
  269.  
  270. FILE FORMAT:
  271.  
  272. # Brackets handling:
  273. # "break":  Break brackets from pre-block code (i.e. ANSI C/C++ style).
  274. # "attach": Attach brackets to pre-block code (i.e. Java/K&R style).
  275. # "linux":  Break definition-block brackets and attach command-block brackets.
  276. # "break-closing-headers": Break brackets before closing headers (e.g. 'else',
  277. #                          'catch', ..).  Should be appended to $brackets=attach
  278. #                          or $brackets=linux.
  279. $BRACKETS=<break | attach | linux | break-closing-headers>
  280.  
  281. # Insert empty lines around unrelated blocks, labels, classes, ...
  282. # "true": default mode
  283. # "all": also insert empty lines around closing headers
  284. #        (e.g. 'else', 'catch', ...).
  285. $BREAK-BLOCKS=<true | false | all>
  286.  
  287. # Break 'else if()' statements into two different lines.
  288. $BREAK-ELSEIFS=<true / false>
  289.  
  290. # Add extra indentation entire blocks (including brackets).
  291. $INDENT-BLOCKS=<true / false>
  292.  
  293. # Add extra indentation to '{' and '}' block brackets.
  294. $INDENT-BRACKETS=<true / false>
  295.  
  296. # Indent 'case XXX:' lines, so that they are flush with
  297. # their bodies.
  298. $INDENT-CASES=<true / false>
  299.  
  300. # Indent 'class' blocks, so that the inner 'public:', 'protected:' and 'private:'
  301. # headers are indented in relation to the class block.
  302. $INDENT-CLASSES=<true / false>
  303.  
  304. # Indent labels so that they appear one indent less than the current indentation
  305. # level, rather than being flushed completely to the left (which is the default).
  306. $INDENT-LABELS=<true / false>
  307.  
  308. # Indent the contents of namespace blocks.
  309. $INDENT-NAMESPACES=<true / false>
  310.  
  311. # Indent multi-line #define statements
  312. INDENT-PREPROCESSOR=<true / false>
  313.  
  314. # Indent using <num> spaces per indent. Not specifying <num>  will result in a
  315. # default  of 4 spacec per indent.
  316. $INDENT-SPACES=<num>
  317.  
  318. # Indent 'switch' blocks, so that the inner 'case XXX:' headers are indented in
  319. # relation to the switch block.
  320. $INDENT-SWITCHES=<true / false>
  321.  
  322. # Indent a Java source file
  323. $JAVA-STYLE=<true / false>
  324.  
  325. # Indent a maximal <num> spaces in a continuous statement, relatively to the
  326. # previous line.
  327. $MAX-INSTATEMENT-INDENT=<num>
  328.  
  329. # Indent a minimal <num> spaces in a continuous conditional belonging to a
  330. # conditional header.
  331. $MIN-CONDITIONAL-INDENT=<num>
  332.  
  333. # Surround symbols with whitespace:
  334. # "paren": Insert space paddings around parenthesies only
  335. # "oper":  Insert space paddings around operators only.
  336. # "all":   Insert space paddings around operators AND parenthesies.
  337. $PAD=<paren | oper | all>
  338.  
  339.  
  340. Example:
  341.  
  342. # K&R indentation scheme
  343. $indent-brackets=false
  344. $indent-spaces=4
  345. $brackets=attach
  346. $indent-classes=false
  347. $indent-switches=false
  348. $indent-namespaces=false
  349.  
  350.  
  351.  
  352. 8. WINDOWS EXPLORER INTEGRATION
  353. --------------------------------------------------------------------------------
  354.  
  355. Create a link to WinHighlight.exe in the SendTo folder of your Windows home
  356. directory. Now you can right-click your source files, and add them to the
  357. Highlight file listbox during startup in the "Send to" pull down menu.
  358.  
  359.  
  360. 9. CONTACT:
  361. --------------------------------------------------------------------------------
  362.  
  363. AndrΘ Simon
  364. andre.simon1@gmx.de
  365. http://www.andre-simon.de/