Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
code2html(1)							  code2html(1)

NAME
       code2html - Converts a program source code to HTML

SYNOPSIS
       (1) code2html [options] [input-file [output-file]]

       (2) code2html -p	[file [alternate-outfile]]

       (3) code2html (as a CGI script; see the section on CGI)

DESCRIPTION
       code2html is a perl script which	converts a program source code to syn-
       tax highlighted HTML, or	any other format for wich rules	are defined.

   (1) OPTIONS
       input-file
	       Is the file which contains the program source code to  be  for-
	       matted.	 If  not  specified  or	a minus	(-) is given, the code
	       will be read from STDIN.

       output-file
	       Is the file to write the	formatted code to.  If	not  specified
	       or a minus (-) is given,	the code will be written to STDOUT.

       -l, --language-mode
	       Specify	the  set of regular expressions	to use.	 These have to
	       be defined in a language	file (see FILES	below).	 To  find  out
	       which language modes are	defined, issue a code2html --modes.

	       This input is treated case-insensitive.

	       If  not	given,	some  heuristics will be used to determine the
	       file language.

       -v, --verbose
	       Prints progress information to STDERR.

       -n, --linenumbers
	       Print out the source code with line numbers.

       -N, --linknumbers
	       Print out the source code with line numbers.   The  linenumbers
	       will  link  to themselves, which	makes it easy to send links to
	       lines.

       -P, --prefix
	       Optional	prefix to use for line number anchors.

       -t, --replace-tabs[=TABSTOP-WIDTH]
	       Replace each occurence of a  <TAB>  character  with  the	 right
	       amount of spaces	to get to the next tabstop.  Default is	a tab-
	       stop width of 8 characters.

       -L, --language-file=LANGUAGE-FILE
	       Specify an alternate file to take the language and  output-for-
	       mat definitions from (see the section on	FILES below).

       -m, --modes
	       Print  all  language modes and output-formats currently defined
	       to STDOUT and exit succesfully. Also prints modes from  a  LAN-
	       GUAGE-FILE given	by --language-file if applicable.

       --fallback=LANG
	       If the language mode given with --language-mode cannot be found
	       then use	this mode.

	       --fallback plain	for instance  is  usefull  when	 code2html  is
	       called from a script to ensure output is	created.

       -h, --help
	       Print a short help and exit succesfully.

       -V, --version
	       Print the program version and exit succesfully.

       -c, --content-type
	       Prints  "Content-Type:  text/html\n\n" (or whatever the output-
	       format defines as a content-type) prior to the rest of the out-
	       put.  Usefull if	the script is ivoked as	a cgi script.

       -o, --output-format
	       Selects	the  output-format.  html is the default.  To find out
	       which outputformats are defined,	issue a	code2html --modes.

       -H, --no-header
	       do not make use of the template defined by  the	output-format.
	       For  HTML  this means that there	will be	no <html>, <head>, and
	       no <typical for patch and CGI modes,pre>	tags.

       --template=FILE
	       overrides the default template for the given output format.  If
	       --no-header  is	given too, this	has no meaning,	since the tem-
	       plate is	ignored	anyway.

       -T, --title
	       Set the title of	the produced output file.  Only	works  if  the
	       template	does support setting the title.

       -w, --linewidth=LINEWIDTH
	       Wrap  lines  after LINEWIDTH characters.	Default	is to not wrap
	       lines at	all.

       -b, --linebreakprefix=LINEPREFIX
	       Use fILINEPREFIX	at the start of	wrapped	lines. Default is  ">>
	       ".

   (2) HTML patching
       code2html -p [file [alternate-outfile]]

       code2html  also	allows you to have inline source code in an html file.
       It can then take	this html file and insert the syntax highlighted code.

       If no file is given, code2html reads from STDIN and writes  to  STDOUT.
       If  just	 one  file is given it replaces	this file with the output.  If
       two files are provided, the first one is	read from and the  second  one
       written to.

       To use this feature, just insert	a like like this into your html	file:

	      <!-- code2html add [options] <file> -->

       the  syntax highlighted file will be inserted at	this position enclosed
       in <pre>	tags.

       All options that	can be given on	the command  line  like	 --linenumbers
       etc. work.  --help, --version, etc. work	too however it is not very in-
       telligent to use	them :).  Using	--output-format	to choose  a  non-HTML
       outputformat is not adviseable.	--content-type is ignored.

       You  may	also write the program's source	code directly in the html file
       with the	following syntax:

	      <!-- code2html add [options]

	      <your program source code	here>

	      -->

       It is usually a good idea to at least give the  --language-mode	option
       to specify the language.

   (3) CGI
       If  the	the script is used as a	CGI script (GATEWAY_INTERFACE environ-
       ment set	and no command line arguments given) code2html reads the argu-
       ments  either  from  the	query string or	from SDTIN.  (methods POST and
       GET).

       --content-type is switched on automatically and the output always  goes
       to STDOUT.

       The following parameters/options	are accepted:

       language-mode - optional
	       `c', `cc', `pas', etc.

	       if  not	given,	some  heuristics are used to find out the lan-
	       guage.

       fallback	- optional
	       `plain',	`c', etc. if language-mode cannot be found,  use  this
	       one

       input-selector -	optional
	       either `file', `cgi-input1', `cgi-input2', or `REDIRECT_URL'

	       default:	file

       filename
	       file to read from if input-selector is `file'

       cgi-input1
	       The  source  code  to  syntax  highlight.   For	example	from a
	       <textarea> or from a upload.  See input-selector.

       cgi-input2
	       The source code	to  syntax  highlight.	 For  example  from  a
	       <textarea> or from a upload.  See input-selector.

       line-numbers - optional
	       `yes', `no' or `link'

	       default:	no

       replace-tabs - optional
	       If 0 then tabs are not replaced,	else replace each occurence of
	       a <TAB> character with the right	amount of spaces to get	to the
	       next tabstop.

	       default:	0

       title - optional
	       Set's the title of the file.

       no-encoding - optional
	       By  default  code2html  tries  to  encode  the output as	either
	       bz2/gz/Z	if the client supports this (HTTP_ACCEPT_ENCODING) and
	       the needed program is available on the server.  You may need to
	       modify @CGI_ENCODING in the script to match your	program	 loca-
	       tions.

	       If  no-encoding	is defined as "true" code2html does not	try to
	       encode the output.

       Why two cgi-inputs you may ask: This is to allow	your users  to	choose
       vie  a  <form>  interface whether they want to insert their file	into a
       <textarea> or user a <browse> button to select their file. See the  ex-
       ample on	my home- page.

       Note  that  if  $FILES_DISALLOWED_IN_CGI	 is  0 it is possbile for your
       users to	read all the files the httpd can read (if you don't run	a cgi-
       wrapper	or  something like this. By default this value is set to 1, so
       file reading via	cgi should not be allowed. You can allow it with  set-
       ting $FILES_DISALLOWED_IN_CGI to	0 at the top of	the script.

       The  input selector REDIRECT_URL	needs a	special	explaination. The file
       name is formed from the two enviroment variables	DOCUMENT_ROOT and  RE-
       DIRECT_URL.

       If  you	want  apache  to  automatically	call code2html for all program
       source code files you may do this by adding these  two  lines  to  your
       srm.conf:

	      AddHandler text/x-sourcecode .c .cc .cpp .pas .h .p

	      Action text/x-sourcecode /cgi-bin/code2html?input-selector=REDI-
	      RECT_URL&foo=

       or something similar to this. In	the  AddHandle	line  you  can	choose
       which extensions	to pass	through	code2html.

       WARNING:	  Do   not   add  .pl  to  this	 line  and  name  this	script
       "code2html.pl". This will result	in a loop.

       Also make sure that you load the	Action module (srm.conf).

       Replace /cgi-bin/code2html with the virtual location  under  which  the
       file  can be accessed. Note the "foo=" part.  Apache appends the	URL of
       the file	to display at the end of the action part. We do	not need  this
       since  we  use  the environment variable	REDIRECT_URL however we	do not
       want to get the url addes to the	input-selector string.	 Therefore  we
       append the "&foo=" part.

       Tnx  to	Kevin Burton <burton@relativity.yi.org>	for the	idea.  He also
       states that

       > It is more powerfull if you use it in an Apache
       > <Directory> tag
       >
       > <Directory /source>
       >
       >  #with	your Action tag	here...	this way you can
       >  #still have regular .java files on your server.
       >
       > </Directory>
       >

EXAMPLE
       assuming	code2html is in	the current directory, you may type

		    code2html -l perl code2html.pl code2html.html

       to convert the script into a html file.

FILES
       Code2html looks for it's	configuration in several places.

       o   the file specified by -L or --language-file if any

       o   the files specified in the  evironment  variable  CODE2HTML_CONFIG,
	   seperated by	colons

       o   user's $HOME/.code2html.config

       o   /usr/local/etc/code2html.config

       o   built in default languages

       Entries in a file that is mentioned earlier in this list	override rules
       from later files.

       The file	structure must be valid	perl code.

       The global variables %LANGUAGE and %STYLESHEET are already defined,  so
       you should not redeclare	them using "my".

       When  you are looking for a model configuration to serve	as a basis for
       your own	configuration file, it is probably best	to start out by	check-
       ing the built-in	definitions at the bottom of code2html.

       If your pattern includes	back references	like a lot patterns do in perl
       for example, then you have to use \2 instead of \1, \3  instead	of  \2
       and so on.  I really don't like this hack but it	is a lot faster.

       Example:

				  <<([^\n]*).*?^\2$

       In this example the perl	<< stuff is matched, i.e. everything from a <<
       until a line that consists of exactly the same string as	behind the  <<
       was.  The \2 references the matched chars in the	parentenses.

       If  you ever write language specific rule files yourself, I'd be	grate-
       ful if you could	send those to me, so I could make them available (with
       full  credits  of  course)  on my homepage for anyone to	grab, whenever
       some of those files suit	someone	else's needs.  Before you  do  so  you
       might  also  have a look	at my site to check wheter someone has already
       written a rule file for your favourite language.

NOTES
       The language recognition	mechanism relies on specific  patterns	within
       the  file name and the content of the processed file, such as file name
       extensions and shebangs (#!).  This means that if the input is  a  pipe
       or  a  socket, the file name does not follow traditional	naming conven-
       tions, or the content of	the processed file is  incomplete,  the	 input
       language	 name  should  be  specified using the --language-mode command
       line parameter.

BUGS
       Please report bugs to code2html@palfrader.org.  This program is still a
       beta release, so	you should expect to find some.
       Also have a look	at my web-site,	perhaps	a new version is available al-
       ready at	http://www.palfrader.org/code2html/.

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

LICENSE
       Copyright (c) 1999, 2000	by Peter Palfrader & others.

       Permission is hereby granted, free of charge, to	any person obtaining a
       copy of this software and associated documentation  files  (the	"Soft-
       ware",  to  deal	in the Software	without	restriction, including without
       limitation the rights to	use, copy, modify, merge, publish, distribute,
       sublicense,  and/or  sell copies	of the Software, and to	permit persons
       to whom the Software is furnished to do so, subject  to	the  following
       conditions:

       The above copyright notice and this permission notice shall be included
       in all copies or	substantial portions of	the Software.

       THE SOFTWARE IS PROVIDED	"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
       OR  IMPLIED,  INCLUDING	BUT  NOT  LIMITED  TO  THE  WARRANTIES OF MER-
       CHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN
       NO  EVENT  SHALL	 THE  AUTHORS  OR  COPYRIGHT HOLDERS BE	LIABLE FOR ANY
       CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN	 ACTION	 OF  CONTRACT,
       TORT OR OTHERWISE, ARISING FROM,	OUT OF OR IN CONNECTION	WITH THE SOFT-
       WARE OR THE USE OR OTHER	DEALINGS IN THE	SOFTWARE.

Mar-2000							  code2html(1)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLE | FILES | NOTES | BUGS | AUTHOR | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=code2html&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help