1code2html(1) code2html(1)
2
6 code2html - Converts a program source code to HTML
7
10 (1) code2html [options] [input-file [output-file]]
11 (2) code2html -p [file [alternate-outfile]]
13 (3) code2html (as a CGI script; see the section on CGI)
15
18 code2html is a perl script which converts a program source code to syn‐
19 tax highlighted HTML, or any other format for wich rules are defined.
20 [1m(1) OPTIONS
23 input-file
24 Is the file which contains the program source code to be for‐
25 matted. If not specified or a minus (-) is given, the code
26 will be read from STDIN.
27 output-file
30 Is the file to write the formatted code to. If not specified
31 or a minus (-) is given, the code will be written to STDOUT.
32 -l, --language-mode
35 Specify the set of regular expressions to use. These have to
36 be defined in a language file (see FILES below). To find out
37 which language modes are defined, issue a code2html --modes.
38 This input is treated case-insensitive.
41 If not given, some heuristics will be used to determine the
44 file language.
45 -v, --verbose
48 Prints progress information to STDERR.
49 -n, --linenumbers
52 Print out the source code with line numbers.
53 -N, --linknumbers
56 Print out the source code with line numbers. The linenumbers
57 will link to themselves, which makes it easy to send links to
58 lines.
59 -P, --prefix
62 Optional prefix to use for line number anchors.
63 -t, --replace-tabs[=TABSTOP-WIDTH]
66 Replace each occurence of a <TAB> character with the right
67 amount of spaces to get to the next tabstop. Default is a tab‐
68 stop width of 8 characters.
69 -L, --language-file=LANGUAGE-FILE
72 Specify an alternate file to take the language and output-for‐
73 mat definitions from (see the section on FILES below).
74 -m, --modes
77 Print all language modes and output-formats currently defined
78 to STDOUT and exit succesfully. Also prints modes from a LAN‐
79 GUAGE-FILE given by --language-file if applicable.
80 --fallback=LANG
83 If the language mode given with --language-mode cannot be found
84 then use this mode.
85 --fallback plain for instance is usefull when code2html is
88 called from a script to ensure output is created.
89 -h, --help
92 Print a short help and exit succesfully.
93 -V, --version
96 Print the program version and exit succesfully.
97 -c, --content-type
100 Prints ”Content-Type: text/html\n\n“ (or whatever the output-
101 format defines as a content-type) prior to the rest of the out‐
102 put. Usefull if the script is ivoked as a cgi script.
103 -o, --output-format
106 Selects the output-format. html is the default. To find out
107 which outputformats are defined, issue a code2html --modes.
108 -H, --no-header
111 do not make use of the template defined by the output-format.
112 For HTML this means that there will be no <html>, <head>, and
113 no <typical for patch and CGI modes,pre> tags.
114 --template=FILE
117 overrides the default template for the given output format. If
118 --no-header is given too, this has no meaning, since the tem‐
119 plate is ignored anyway.
120 -T, --title
123 Set the title of the produced output file. Only works if the
124 template does support setting the title.
125 -w, --linewidth=LINEWIDTH
128 Wrap lines after LINEWIDTH characters. Default is to not wrap
129 lines at all.
130 -b, --linebreakprefix=LINEPREFIX
133 Use fILINEPREFIX at the start of wrapped lines. Default is "»
134 ".
135 [1m(2) HTML patching
140 code2html -p [file [alternate-outfile]]
141 code2html also allows you to have inline source code in an html file.
144 It can then take this html file and insert the syntax highlighted code.
145 If no file is given, code2html reads from STDIN and writes to STDOUT.
148 If just one file is given it replaces this file with the output. If
149 two files are provided, the first one is read from and the second one
150 written to.
151 To use this feature, just insert a like like this into your html file:
154 <!-- code2html add [options] <file> -->
157 the syntax highlighted file will be inserted at this position enclosed
160 in <pre> tags.
161 All options that can be given on the command line like --linenumbers
164 etc. work. --help, --version, etc. work too however it is not very
165 intelligent to use them :). Using --output-format to choose a non-HTML
166 outputformat is not adviseable. --content-type is ignored.
167 You may also write the program's source code directly in the html file
170 with the following syntax:
171 <!-- code2html add [options]
174 <your program source code here>
176 -->
178 It is usually a good idea to at least give the --language-mode option
181 to specify the language.
182 [1m(3) CGI
185 If the the script is used as a CGI script (GATEWAY_INTERFACE environ‐
186 ment set and no command line arguments given) code2html reads the argu‐
187 ments either from the query string or from SDTIN. (methods POST and
188 GET).
189 --content-type is switched on automatically and the output always goes
192 to STDOUT.
193 The following parameters/options are accepted:
196 language-mode - optional
199 `c', `cc', `pas', etc.
200 if not given, some heuristics are used to find out the lan‐
203 guage.
204 fallback - optional
207 `plain', `c', etc. if language-mode cannot be found, use this
208 one
209 input-selector - optional
212 either `file', `cgi-input1', `cgi-input2', or `REDIRECT_URL'
213 default: file
215 filename
218 file to read from if input-selector is `file'
219 cgi-input1
222 The source code to syntax highlight. For example from a
223 <textarea> or from a upload. See input-selector.
224 cgi-input2
227 The source code to syntax highlight. For example from a
228 <textarea> or from a upload. See input-selector.
229 line-numbers - optional
232 `yes', `no' or `link'
233 default: no
235 replace-tabs - optional
238 If 0 then tabs are not replaced, else replace each occurence of
239 a <TAB> character with the right amount of spaces to get to the
240 next tabstop.
241 default: 0
243 title - optional
246 Set's the title of the file.
247 no-encoding - optional
250 By default code2html tries to encode the output as either
251 bz2/gz/Z if the client supports this (HTTP_ACCEPT_ENCODING) and
252 the needed program is available on the server. You may need to
253 modify @CGI_ENCODING in the script to match your program loca‐
254 tions.
255 If no-encoding is defined as “true” code2html does not try to
258 encode the output.
259 Why two cgi-inputs you may ask: This is to allow your users to choose
262 vie a <form> interface whether they want to insert their file into a
263 <textarea> or user a <browse> button to select their file. See the
264 example on my home- page.
265 Note that if $FILES_DISALLOWED_IN_CGI is 0 it is possbile for your
268 users to read all the files the httpd can read (if you don't run a cgi-
269 wrapper or something like this. By default this value is set to 1, so
270 file reading via cgi should not be allowed. You can allow it with set‐
271 ting $FILES_DISALLOWED_IN_CGI to 0 at the top of the script.
272 The input selector REDIRECT_URL needs a special explaination. The file
275 name is formed from the two enviroment variables DOCUMENT_ROOT and RE‐
276 DIRECT_URL.
277 If you want apache to automatically call code2html for all program
280 source code files you may do this by adding these two lines to your
281 srm.conf:
282 AddHandler text/x-sourcecode .c .cc .cpp .pas .h .p
285 Action text/x-sourcecode /cgi-bin/code2html?input-selector=REDI‐
287 RECT_URL&foo=
288 or something similar to this. In the AddHandle line you can choose
291 which extensions to pass through code2html.
292 WARNING: Do not add .pl to this line and name this script
295 “code2html.pl”. This will result in a loop.
296 Also make sure that you load the Action module (srm.conf).
299 Replace /cgi-bin/code2html with the virtual location under which the
302 file can be accessed. Note the “foo=” part. Apache appends the URL of
303 the file to display at the end of the action part. We do not need this
304 since we use the environment variable REDIRECT_URL however we do not
305 want to get the url addes to the input-selector string. Therefore we
306 append the “&foo=” part.
307 Tnx to Kevin Burton <burton@relativity.yi.org> for the idea. He also
310 states that
311 > It is more powerfull if you use it in an Apache
314 > <Directory> tag
315 >
316 > <Directory /source>
317 >
318 > #with your Action tag here... this way you can
319 > #still have regular .java files on your server.
320 >
321 > </Directory>
322 >
323
327 assuming code2html is in the current directory, you may type
328 code2html -l perl code2html.pl code2html.html
330 to convert the script into a html file.
332
335 Code2html looks for it's configuration in several places.
336 · the file specified by -L or --language-file if any
339 · the files specified in the evironment variable CODE2HTML_CONFIG,
341 seperated by colons
342 · user's $HOME/.code2html.config
344 · /etc/code2html.config
346 · built in default languages
348 Entries in a file that is mentioned earlier in this list override rules
351 from later files.
352 The file structure must be valid perl code.
355 The global variables %LANGUAGE and %STYLESHEET are already defined, so
358 you should not redeclare them using “my”.
359 When you are looking for a model configuration to serve as a basis for
362 your own configuration file, it is probably best to start out by check‐
363 ing the built-in definitions at the bottom of code2html.
364 If your pattern includes back references like a lot patterns do in perl
367 for example, then you have to use \2 instead of \1, \3 instead of \2
368 and so on. I really don't like this hack but it is a lot faster.
369 Example:
372 <<([^\n]*).*?^\2$
374 In this example the perl << stuff is matched, i.e. everything from a <<
377 until a line that consists of exactly the same string as behind the <<
378 was. The \2 references the matched chars in the parentenses.
379 If you ever write language specific rule files yourself, I'd be grate‐
382 ful if you could send those to me, so I could make them available (with
383 full credits of course) on my homepage for anyone to grab, whenever
384 some of those files suit someone else's needs. Before you do so you
385 might also have a look at my site to check wheter someone has already
386 written a rule file for your favourite language.
387
390 The language recognition mechanism relies on specific patterns within
391 the file name and the content of the processed file, such as file name
392 extensions and shebangs (#!). This means that if the input is a pipe
393 or a socket, the file name does not follow traditional naming conven‐
394 tions, or the content of the processed file is incomplete, the input
395 language name should be specified using the --language-mode command
396 line parameter.
397
400 Please report bugs to code2html@palfrader.org. This program is still a
401 beta release, so you should expect to find some.
402 Also have a look at my web-site, perhaps a new version is available
403 already at http://www.palfrader.org/code2html/.
404
407 Peter Palfrader, <code2html@palfrader.org> A lot of other people. See
408 contributers in the file itself.
409
412 Copyright (c) 1999, 2000 by Peter Palfrader & others.
413 Permission is hereby granted, free of charge, to any person obtaining a
416 copy of this software and associated documentation files (the “Soft‐
417 ware”, to deal in the Software without restriction, including without
418 limitation the rights to use, copy, modify, merge, publish, distribute,
419 sublicense, and/or sell copies of the Software, and to permit persons
420 to whom the Software is furnished to do so, subject to the following
421 conditions:
422 The above copyright notice and this permission notice shall be included
425 in all copies or substantial portions of the Software.
426 THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS
429 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MER‐
430 CHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
431 NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
432 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
433 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFT‐
434 WARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
435Mar-2000 code2html(1)