code2html(1)

✨ code2html(1) ✨

okay bestie, sit down, hydrate, because this one is a whole journey 💖 code2html is a perl script that takes your source code and turns it into syntax-highlighted HTML — or literally any other format you've defined rules for. it's giving "I made a thing and it slaps", and we're gonna read the whole manual together. no skipping, no scrolling past the boring bits, I got you 🫶

---

🌸 NAME 🌸

code2html — Converts a program source code to HTML 💅

---

📜 SYNOPSIS 📜

three whole entry vibes, pick your fighter:

(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. it converts a program source code into syntax-highlighted HTML — or honestly any other format you want, as long as the rules for it are defined. that's it, that's the whole plot. she's simple, she's powerful, she's iconic 👑

🛠️ (1) OPTIONS 🛠️

• input-file — the file holding the program source code you want formatted. if you don't give one, or you give a minus (-), the code gets read from STDIN. lowkey convenient ngl.
• output-file — the file the formatted code gets written to. if you don't give one, or you give a minus (-), it goes to STDOUT instead.

---

• -l, --language-mode — pick which set of regular expressions to use. these have to be defined in a language file (peep the FILES section below, bestie). wanna know which language modes exist? just run code2html --modes and she'll tell you. this input is treated case-insensitive. and if you don't give it at all, some heuristics get used to figure out the file's language on their own. main character energy, honestly.
• -v, --verbose — prints progress info to STDERR, so you can watch her cook 🔥
• -n, --linenumbers — prints the source code out with line numbers. cute, organized, very Type A of you.
• -N, --linknumbers — also prints the source code with line numbers, BUT the line numbers link to themselves, which makes it easy to send someone a link straight to a line. obsessed.
• -P, --prefix — an optional prefix to use for those line number anchors.
• -t, --replace-tabs[=TABSTOP-WIDTH] — replaces every occurrence of a <TAB> character with the right amount of spaces to land on the next tabstop. default tabstop width is 8 characters. no more cursed tab chaos 💀
• -L, --language-file=LANGUAGE-FILE — point at an alternate file to pull the language and output-format definitions from (again, see FILES below).
• -m, --modes — prints all currently defined language modes and output-formats to STDOUT, then exits successfully. it also prints modes from a LANGUAGE-FILE given by --language-file if that applies. go look at your options, queen ✨
• --fallback=LANG — if the language mode you asked for with --language-mode can't be found, fall back to this one instead. for example --fallback plain is genuinely useful when code2html is called from a script and you just need output to exist, no matter what.
• -h, --help — prints a short help and exits successfully.
• -V, --version — prints the program version and exits successfully.
• -c, --content-type — prints Content-Type: text/html\n\n (or whatever your output-format defines as its content-type) before the rest of the output. super useful when the script is invoked as a CGI script.
• -o, --output-format — selects the output-format. html is the default. want to see what outputformats are defined? you already know the answer, bestie: code2html --modes.
• -H, --no-header — do not use the template defined by the output-format. for HTML that means no <html>, no <head>, and no <pre> tags (that <pre> situation being typical for patch and CGI modes).
• --template=FILE — overrides the default template for the given output format. heads up: if --no-header is given too, this means nothing at all, because the template gets ignored anyway. sorry girl.
• -T, --title — sets the title of the produced output file. only works if the template actually supports setting a title, so no promises.
• -w, --linewidth=LINEWIDTH — wraps lines after LINEWIDTH characters. default is to not wrap lines at all. let her be long, let her breathe.
• -b, --linebreakprefix=LINEPREFIX — uses LINEPREFIX at the start of wrapped lines (the original page writes it as fILINEPREFIX, which is giving typo era, but you get it 💀). default is "» ".

---

🎀 (2) HTML patching 🎀

code2html -p [file [alternate-outfile]]

code2html also lets you have inline source code inside an html file. she'll take that html file and insert the syntax-highlighted code right in there. so cozy.

• if no file is given, code2html reads from STDIN and writes to STDOUT.
• if just one file is given, she replaces that file with the output.
• if two files are provided, the first one gets read from and the second one gets written to.

to use this feature, just drop a line like this into your html file:

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

the syntax-highlighted file will be inserted at that exact position, wrapped up all snug in <pre> tags 🫶

all the options you can give on the command line — --linenumbers, etc. — work here too. --help, --version, and friends also work, though it is not very intelligent to use them in this context :). using --output-format to choose a non-HTML outputformat is not advisable. and --content-type is ignored entirely.

you can also write the program's source code directly in the html file, like this:

<!-- code2html add [options]

<your program source code here>

-->

it's usually a good idea to at least pass --language-mode so she knows what language she's looking at.

---

🐚 (3) CGI 🐚

if the script is used as a CGI script (that's GATEWAY_INTERFACE environment set, and no command line arguments given), code2html reads the arguments either from the query string or from STDIN. the methods are POST and GET, as always.

--content-type gets switched on automatically, and the output always goes to STDOUT. no notes.

the following parameters/options are accepted:

• language-mode — optional. like c, cc, pas, etc. if it's not given, some heuristics are used to figure out the language.
• fallback — optional. like plain, c, etc. if language-mode can't be found, use this one.
• input-selector — optional. either file, cgi-input1, cgi-input2, or REDIRECT_URL. default: file.
• filename — the file to read from, if input-selector is file.
• cgi-input1 — the source code to syntax highlight. for example from a <textarea> or from an upload. see input-selector.
• cgi-input2 — the source code to syntax highlight. for example from a <textarea> or from an upload. see input-selector.
• line-numbers — optional. yes, no, or link. default: no.
• replace-tabs — optional. if 0, then tabs are not replaced; otherwise every occurrence of a <TAB> character gets replaced with the right amount of spaces to reach the next tabstop. default: 0.
• title — optional. sets 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 it (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 locations. if no-encoding is defined as "true", code2html does not try to encode the output.

why two cgi-inputs, you may ask? it's so your users can choose, via a <form> interface, whether they want to paste their file into a <textarea> or use a <browse> button to select their file. see the example on the homepage 💖

also, heads up: if $FILES_DISALLOWED_IN_CGI is 0, it's possible for your users to read all the files the httpd can read (unless you run a cgi-wrapper or something like that). by default this value is set to 1, so file reading via cgi should not be allowed. you can allow it by setting $FILES_DISALLOWED_IN_CGI to 0 at the top of the script. your call, bestie, but be careful 🫣

the input selector REDIRECT_URL needs a special explanation. the file name is formed from the two environment variables DOCUMENT_ROOT and REDIRECT_URL.

if you want apache to automatically call code2html for all program source code files, you can 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=REDIRECT_URL&foo=

or something similar to this. in the AddHandler line you can choose which extensions get passed through code2html.

WARNING: do not add .pl to this line and name this script code2html.pl. this will result in a loop. we do not want that, we want peace.

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

replace /cgi-bin/code2html with the virtual location under which the file can be accessed. and note the foo= part: apache appends the URL of the file to display at the end of the action part. we don't need that, since we use the environment variable REDIRECT_URL — but we also don't want the url added to the input-selector string. therefore we append that &foo= part. mystery solved 🔍

thanks 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 an html file. look at her go ✨

---

📂 FILES 📂

code2html looks for its configuration in several places.

• the file specified by -L or --language-file, if any
• the files specified in the environment variable CODE2HTML_CONFIG, separated by colons
• user's $HOME/.code2html.config
• /etc/code2html.config
• built-in default languages

entries in a file that's mentioned earlier in this list override rules from later files. first one wins, no take-backs.

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're looking for a model configuration to serve as a basis for your own config file, it's probably best to start by checking the built-in definitions at the bottom of code2html.

if your pattern includes back references — like a lot of patterns do in perl, for example — then you have to use \2 instead of \1, \3 instead of \2, and so on. the author really doesn't like this hack, but it's a lot faster. so it stays 💀

example:

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

in this example the perl << stuff is matched — that's everything from a << until a line that consists of exactly the same string as the one behind the <<. the \2 references the matched chars in the parentheses.

if you ever write language-specific rule files yourself, the author would be grateful if you could send those over, so they can be made available (with full credits, of course) on the homepage for anyone to grab, whenever one of those files suits someone else's needs. before you do, you might also have a look at the site to check whether someone has already written a rule file for your favourite language. sharing is caring, bestie 🫶

🧠 NOTES 🧠

okay so bestie, the language recognition thing? it's lowkey just vibes-based pattern matching. it peeks at specific patterns hiding in the file name and in the content of the file it's chewing on — stuff like file name extensions and shebangs (#!) ✨

which means 👀 if your input is a pipe or a socket, or the file name is out here not following traditional naming conventions, or the content of the processed file is incomplete, then it literally cannot guess, bestie 💀

so in those cases you gotta specify the input language name yourself with the --language-mode command line parameter. no cap. it's giving "just tell me what it is" 💅

---

🐛 BUGS 🐛

found a bug? pls pls pls report it to code2html@palfrader.org 🫶 this program is still a beta release, so bestie, you should expect to find some. it's giving "we're so back but also not quite" 😭

also bestie, go have a look at the web-site, maybe a new version is already available at http://www.palfrader.org/code2html/ 🌈

---

👑 AUTHOR 👑

Peter Palfrader, <code2html@palfrader.org> 💖

A lot of other people. See contributers in the file itself. 🎀 (yes the original says "contributers", we respect the typo, it's iconic)

---

📜 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 “Software”), 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 MERCHANTABILITY, 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 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

tl;dr bestie: it's free, use it, sell it, remix it — just keep the copyright notice, and if it explodes, that's on you, not on Peter 💅

---

and that's the whole page bestie!! 🦋✨ this one's from Mar-2000, so it's lowkey vintage but highkey still serving, and it's code2html(1) — the one and only 👑 go forth and convert ur code, mwah 💖🎀🌸