1code2html(1)                                                      code2html(1)
2
3
4

NAME

6       code2html - Converts a program source code to HTML
7
8

SYNOPSIS

10       (1) code2html [options] [input-file [output-file]]
11
12       (2) code2html -p [file [alternate-outfile]]
13
14       (3) code2html (as a CGI script; see the section on CGI)
15
16

DESCRIPTION

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
21
22   (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
28
29       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
33
34       -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
39
40               This input is treated case-insensitive.
41
42
43               If  not  given,  some  heuristics will be used to determine the
44               file language.
45
46
47       -v, --verbose
48               Prints progress information to STDERR.
49
50
51       -n, --linenumbers
52               Print out the source code with line numbers.
53
54
55       -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
60
61       -P, --prefix
62               Optional prefix to use for line number anchors.
63
64
65       -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
70
71       -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
75
76       -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
81
82       --fallback=LANG
83               If the language mode given with --language-mode cannot be found
84               then use this mode.
85
86
87               --fallback plain for instance  is  usefull  when  code2html  is
88               called from a script to ensure output is created.
89
90
91       -h, --help
92               Print a short help and exit succesfully.
93
94
95       -V, --version
96               Print the program version and exit succesfully.
97
98
99       -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
104
105       -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
109
110       -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
115
116       --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
121
122       -T, --title
123               Set the title of the produced output file.  Only works  if  the
124               template does support setting the title.
125
126
127       -w, --linewidth=LINEWIDTH
128               Wrap  lines  after LINEWIDTH characters. Default is to not wrap
129               lines at all.
130
131
132       -b, --linebreakprefix=LINEPREFIX
133               Use fILINEPREFIX at the start of wrapped lines. Default  is  "»
134               ".
135
136
137
138
139   (2) HTML patching
140       code2html -p [file [alternate-outfile]]
141
142
143       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
146
147       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
152
153       To use this feature, just insert a like like this into your html file:
154
155
156              <!-- code2html add [options] <file> -->
157
158
159       the  syntax highlighted file will be inserted at this position enclosed
160       in <pre> tags.
161
162
163       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
168
169       You  may also write the program's source code directly in the html file
170       with the following syntax:
171
172
173              <!-- code2html add [options]
174
175              <your program source code here>
176
177              -->
178
179
180       It is usually a good idea to at least give the  --language-mode  option
181       to specify the language.
182
183
184   (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
190
191       --content-type is switched on automatically and the output always  goes
192       to STDOUT.
193
194
195       The following parameters/options are accepted:
196
197
198       language-mode - optional
199               `c', `cc', `pas', etc.
200
201
202               if  not  given,  some  heuristics are used to find out the lan‐
203               guage.
204
205
206       fallback - optional
207               `plain', `c', etc. if language-mode cannot be found,  use  this
208               one
209
210
211       input-selector - optional
212               either `file', `cgi-input1', `cgi-input2', or `REDIRECT_URL'
213
214               default: file
215
216
217       filename
218               file to read from if input-selector is `file'
219
220
221       cgi-input1
222               The  source  code  to  syntax  highlight.   For  example from a
223               <textarea> or from a upload.  See input-selector.
224
225
226       cgi-input2
227               The source code  to  syntax  highlight.   For  example  from  a
228               <textarea> or from a upload.  See input-selector.
229
230
231       line-numbers - optional
232               `yes', `no' or `link'
233
234               default: no
235
236
237       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
242               default: 0
243
244
245       title - optional
246               Set's the title of the file.
247
248
249       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
256
257               If  no-encoding  is defined as “true” code2html does not try to
258               encode the output.
259
260
261       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
266
267       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
273
274       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
278
279       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
283
284              AddHandler text/x-sourcecode .c .cc .cpp .pas .h .p
285
286              Action text/x-sourcecode /cgi-bin/code2html?input-selector=REDI‐
287              RECT_URL&foo=
288
289
290       or something similar to this. In the  AddHandle  line  you  can  choose
291       which extensions to pass through code2html.
292
293
294       WARNING:   Do   not   add  .pl  to  this  line  and  name  this  script
295       “code2html.pl”. This will result in a loop.
296
297
298       Also make sure that you load the Action module (srm.conf).
299
300
301       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
308
309       Tnx  to  Kevin Burton <burton@relativity.yi.org> for the idea.  He also
310       states that
311
312
313       > 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
324
325

EXAMPLE

327       assuming code2html is in the current directory, you may type
328
329                    code2html -l perl code2html.pl code2html.html
330
331       to convert the script into a html file.
332
333

FILES

335       Code2html looks for it's configuration in several places.
336
337
338       ·   the file specified by -L or --language-file if any
339
340       ·   the files specified in the  evironment  variable  CODE2HTML_CONFIG,
341           seperated by colons
342
343       ·   user's $HOME/.code2html.config
344
345       ·   /etc/code2html.config
346
347       ·   built in default languages
348
349
350       Entries in a file that is mentioned earlier in this list override rules
351       from later files.
352
353
354       The file structure must be valid perl code.
355
356
357       The global variables %LANGUAGE and %STYLESHEET are already defined,  so
358       you should not redeclare them using “my”.
359
360
361       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
365
366       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
370
371       Example:
372
373                                  <<([^\n]*).*?^\2$
374
375
376       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
380
381       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
388

NOTES

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
398

BUGS

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
405

AUTHOR

407       Peter Palfrader, <code2html@palfrader.org> A lot of other people.   See
408       contributers in the file itself.
409
410

LICENSE

412       Copyright (c) 1999, 2000 by Peter Palfrader & others.
413
414
415       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
423
424       The above copyright notice and this permission notice shall be included
425       in all copies or substantial portions of the Software.
426
427
428       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.
435
436
437
438Mar-2000                                                          code2html(1)
Impressum