Commit 650693a1 authored by saalen's avatar saalen

revised docs

git-svn-id: https://svn.code.sf.net/p/syntaxhighlight/code@196 b214f192-c5d8-4e29-a392-b12ed3af51bf
parent 08938989
......@@ -2,7 +2,7 @@ CHANGELOG Highlight
highlight 3.35
24.02.2017
28.02.2017
-fixed code folding plugin to support Ruby conditional modifiers
-fixed JSON definition (thanks to Timothee Cour)
......@@ -11,6 +11,7 @@ highlight 3.35
-added GDScript definition and edit-godot theme (thanks to Tristano Ajmone)
-updated SWIG code samples
-updated Artistic Style lib (SVN Rev. 553)
-revised docs
-CLI: fixed creation of hidden files if output filename is prepended by its input path
-CLI: added switch --stdout (https://sourceforge.net/p/syntaxhighlight/bugs/14/)
......
......@@ -36,7 +36,7 @@ CONTENT
4.1 SAMPLE SCRIPTS
4.2 SWIG
4.3 TCL
4.3 THIRD PARTY SCRIPTS AND PLUG-INS
4.4 THIRD PARTY SCRIPTS AND PLUG-INS
5. BUILDING AND INSTALLING
5.1 PRECOMPILED PACKAGES
......@@ -59,7 +59,7 @@ Language definitions and colour themes are customizable.
Highlight was designed to offer a flexible but easy to use syntax highlighter
for several output formats. No syntax or colouring information is hardcoded,
instead all relevant data is stored in configuration scripts. These Lua scripts
may be altered or enhanced with plug-in scripts.
may be altered and enhanced with plug-in scripts.
1.2 FEATURE LIST
......@@ -102,8 +102,8 @@ main.cpp as input file:
highlight < main.cpp > main.cpp.html --syntax cpp
You will find the HTML file and highlight.css in the working directory.
If you use IO redirection (see 2nd example), you must define the programming
language using --syntax.
If you use IO redirection (2nd example), you must define the programming
language with --syntax.
- Generate HTML with embedded CSS definitions and line numbers:
highlight -i main.cpp -o main.cpp.html --include-style --line-numbers
......@@ -111,15 +111,13 @@ main.cpp as input file:
- Generate HTML with inline CSS definitions:
highlight -i main.cpp -o main.cpp.html --inline-css
- Generate HTML using "horstmann" source formatting style and "neon" colour
theme:
highlight -i main.cpp -o main.cpp.html --reformat horstmann --style neon
- Generate LaTeX:
highlight --out-format=latex -i main.cpp -o main.cpp.tex
- Generate LaTeX using "horstmann" source formatting style and "neon" colour
theme:
highlight -O latex -i main.cpp -o main.cpp.tex --reformat horstmann --style neon
The following output formats may be defined with --out-format:
html: HTML5
html: HTML5 (default)
xhtml: XHTML 1.1
tex: Plain TeX
latex: LaTeX
......@@ -132,9 +130,6 @@ main.cpp as input file:
xterm256: Terminal 256 color escape codes
truecolor: Terminal 16m color escape codes
Default output is HTML if no other format is specified.
- Customize font settings:
highlight --syntax ada --font-size 12 --font "'Courier New',monospace"
highlight --syntax ada --out-format=latex --font-size tiny --font sffamily
......@@ -315,8 +310,8 @@ performance (recommended for usage in shell scripts).
HTML, TeX, LaTeX and SVG output
-------------------------------
The HTML, TeX, LaTeX and SVG output formats allow to reference style definition
files which contain the formatting information (stylesheets).
The HTML, TeX, LaTeX and SVG output formats allow to reference a stylesheet
file which contains the formatting information.
In HTML and SVG output, this file contains CSS definitions and is saved as
'highlight.css'. In LaTeX and TeX, it contains macro definitions, and is saved
......@@ -329,8 +324,8 @@ are stored in this directory.
Use --include-style to embed the style information in the output documents
without referencing a stylesheet.
Referenced style definitions have the advantage to share all formatting
information in a single file, which affects all referencing documents.
Referenced stylesheets have the advantage to share all formatting information
in a single file, which affects all referencing documents.
With --style-infile you define a file to be included in the final formatting
information of the document. This way you enhance or redefine the default
......@@ -361,16 +356,6 @@ highlight -S txt --out-format=latex README > README.tex
Examples
--------
The following commands write the content of hello.c to hello.html:
highlight -o hello.html -i hello.c
highlight -o hello.html hello.c
highlight -o hello.html --syntax c < hello.c
highlight --syntax c < hello.c > hello.html
Apart from hello.html, a file highlight.css is generated in the current working
directory.
highlight --out-format=xhtml --batch-recursive '*.cpp' --outdir ~/html_code/
This command converts all *.cpp files in the current directory and its sub-
directories to xhtml files, and stores the output in /home/you/html_code.
......@@ -416,7 +401,7 @@ Highlight nested code without starting delimiter
If a file starts with an embedded code section which misses an appropriate opening
delimiter, the --start-nested option will switch to the nested language mode.
This can happen with LuaTeX files:
This can be useful with LuaTeX files:
highlight luatex.tex --latex --start-nested=inc_luatex
inc_luatex is a Lua language definition with TeX line comments.
......@@ -441,6 +426,11 @@ Remove an UTF8 BOM:
Use --validate-input to get rid of UTF8 byte order marks.
Force output to stdout
----------------------
Use --stdout to write output files in batch mode to stdout.
Portable GUI (Windows build)
----------------------------
......@@ -671,10 +661,10 @@ Number = Attributes (Formatting of numbers)
Escape = Attributes (Formatting of escape sequences)
Interpolation = Attributes (Formatting of interpolation sequences)
String = Attributes (Formatting of strings)
Interpolation = Attributes (Formatting of interpolation sequences)
PreProcessor = Attributes (Formatting of preprocessor directives)
StringPreProc = Attributes (Formatting of strings within
......@@ -730,14 +720,14 @@ macros, constants etc.
You define a new group in two steps:
1. Define a new group in your language definition (lang file):
1. Define a new group in your language definition:
Keywords = {
-- add your keyword description:
{Id=5, List = {"ERROR", "DEBUG", "WARN"} }
}
2. Add a corresponding highlighting style in your colour theme (theme file):
2. Add a corresponding highlighting style in your colour theme:
Keywords= {
--add your keyword style as 5th item in the list:
......@@ -863,7 +853,7 @@ Highlight is written in ISO C++. The following packages are available:
The website www.andre-simon.de offers links to precompiled packages for several
operating systems (like Debian, Arch Linux, Ubuntu, Darwin, FreeBSD).
The website distributes the latest upstream sources.
Threre is also a Sourceforge project available:
There is also a Sourceforge project:
http://sourceforge.net/projects/syntaxhighlight/
Source tarball
......@@ -906,9 +896,9 @@ The file INSTALL contains details about package contents and installation.
5.2 BUILDING DEPENDENCIES
-------------------------------------------------------------------------------
Highlight is known to compile with gcc and suncc.
Highlight is known to compile with gcc and clang.
It depends on Boost headers and Lua 5.x/LuaJit developer packages.
The optional GUI depends on Qt4/Qt5 developer packages.
The optional GUI depends on Qt5 developer packages.
Please see the makefile for further options.
......
......@@ -114,15 +114,13 @@ namens main.cpp erzeugt:
- HTML mit direkter CSS-Formatierung ausgeben:
highlight -i main.cpp -o main.cpp.html --inline-css
- HTML mit Code-Formatierung im "horstmann"-Stil und dem Farbschema "Neon"
- LaTeX mit Code-Formatierung im "horstmann"-Stil und dem Farbschema "Neon"
ausgeben:
highlight -i main.cpp -o main.cpp.html --reformat horstmann --style neon
- LaTeX ausgeben:
highlight --latex -i main.cpp -o main.cpp.tex
highlight -O latex -i main.cpp -o main.cpp.tex --reformat horstmann --style neon
Folgende Ausgabeformate koennen mit --out-format bestimmt werden:
html: HTML5
html: HTML5 (Standard)
xhtml: XHTML 1.1
tex: Plain TeX
latex: LaTeX
......@@ -135,9 +133,6 @@ namens main.cpp erzeugt:
xterm256: Terminal 256 color escape codes
truecolor: Terminal 16m color escape codes
HTML wird als Standard ausgegeben, wenn kein anderes Format mit --out-format
bestimmt wurde.
- Font und Schriftgroesse anpassen:
highlight --syntax ada --font-size 12 --font "'Courier New',monospace"
highlight --syntax ada --out-format=latex --font-size tiny --font sffamily
......@@ -321,14 +316,12 @@ Die --outdir Option ist im Batch Modus besonders nuetzlich. In Skripten sollte
HTML, TeX, LaTeX und SVG Ausgabe:
--------------------------------
Die HTML, TeX, LaTeX und SVG-Formate erlauben die Einbindung von externen Dateien,
welche die Formatierungsinformationen enthalten ("Stylesheets").
Die HTML, TeX, LaTeX und SVG-Formate erlauben die Einbindung von Stylesheets,
welche die Formatierungsinformationen enthalten.
Bei der HTML- und SVG-Ausgabe enthaelt diese Datei CSS-Definitionen und wird, wenn
nicht anders angegeben, als "highlight.css" gespeichert.
Bei TeX und LaTeX enthaelt die Datei Makros, und wird per Default als
"highlight.sty" gespeichert.
nicht anders angegeben, als "highlight.css" gespeichert. Bei TeX und LaTeX enthaelt
die Datei Makros, und wird per Default als "highlight.sty" gespeichert.
Name und Pfad des Stylesheets werden mit --style-outfile bestimmt.
Wenn --outdir definiert ist, wird auch das Stylesheet im angegebenen
......@@ -372,15 +365,6 @@ highlight -S txt --out-format=latex README > readme.tex
Beispiele:
----------
Die folgenden Kommandos schreiben den Inhalt von hello.c nach hello.html:
highlight -o hello.html -i hello.c
highlight -o hello.html hello.c
highlight -o hello.html --syntax c < hello.c
highlight --syntax c < hello.c > hello.html
Neben hello.html wird highlight.css im aktuellen Verzeichnis erzeugt.
highlight --out-format=xhtml --batch-recursive '*.cpp' --outdir ~/html_code/
Dieses Kommando konvertiert alle *.cpp Dateien im aktuellen Verzeichnis und den
Unterverzeichnissen in XHTML-Dateien, und speichert die Ausgabe in
......@@ -455,6 +439,11 @@ UTF8 BOM entfernen:
Geben Sie --validate-input an, um das UTF8 Byte Order Mark (Startsequenz) zu
entfernen.
Ausgabe in stdout erzwingen
---------------------------
Mit --stdout wird die Ausgabe auch im Batch-Modus nach stdout ausgegeben.
Portable GUI (Windows build)
----------------------------
......@@ -690,10 +679,10 @@ Number = Attributes (Formatierung von Zahlen)
Escape = Attributes (Formatierung von Escape-Sequenzen)
Interpolation = Attributes (Formatierung von Interpolationen)
String = Attributes (Formatierung von Strings)
Interpolation = Attributes (Formatierung von Interpolationen)
PreProcessor = Attributes (Formatierung von Praeprozessor-Direktiven)
StringPreProc = Attributes (Formatierung von Strings in
......@@ -751,14 +740,14 @@ Makros oder Konstanten gesondert hervorheben moechten.
Eine Gruppe wird in zwei Schritten definiert:
1. Beschreibung der Gruppe in der Sprachdefinition (Lang-Datei):
1. Beschreibung der Gruppe in der Sprachdefinition:
Keywords = {
-- fuegen Sie die Beschreibung an:
{Id=5, List = {"ERROR", "DEBUG", "WARN"} }
}
2. Festlegung des dazugehoerigen Farbstils im Farb-Schema (Theme-Datei)
2. Festlegung des dazugehoerigen Farbstils im Farb-Schema:
Keywords= {
--Stil als fuenften Eintrag hinterlegen:
......@@ -927,9 +916,9 @@ In INSTALL befinden sich weitere Informationen zu Paketinhalt und Installation.
5.2 KOMPILIER-ABHAENGIGKEITEN
-------------------------------------------------------------------------------
Highlight kompiliert zumindest mit gcc und suncc. Zum Kompilieren sind Boost
Highlight kompiliert zumindest mit gcc und clang. Zum Kompilieren sind Boost
Header-Pakete und Lua5.x/LuaJit Development-Pakete noetig.
Die optionale GUI benoetigt die Qt4/Qt5 Development-Pakete.
Die optionale GUI benoetigt Qt5 Development-Pakete.
Im Makefile finden Sie weitere Informationen.
......
......@@ -119,11 +119,6 @@ HL_STRING_END: number
HL_UNKNOWN: number
HL_REJECT: number
Read only (other):
HL_PLUGIN_PARAM: string (set with --plug-in-param)
HL_LANG_DIR: string (path of language definition directory)
Read only (output document format):
HL_OUTPUT: number (selected format)
......@@ -139,6 +134,11 @@ HL_FORMAT_BBCODE: number
HL_FORMAT_PANGO: number
HL_FORMAT_ODT: number
Read only (other):
HL_PLUGIN_PARAM: string (set with --plug-in-param)
HL_LANG_DIR: string (path of language definition directory)
Functions:
AddKeyword: function
......@@ -227,7 +227,7 @@ Decorate(token, state, kwGroupID, stateTrace)
kwGroupID: if state is HL_KEYWORD, the parameter
contains the keyword group ID
stateTrace: string containing past states of the current line;
separated by ';', limited to 100 entries
separated by ';'; limited to 100 entries
Returns: Altered token string or nothing if original token should be
outputted
......@@ -284,10 +284,6 @@ Operator: table
LineComment: table
Keywords: table
Custom theme items:
Injections: table
Read only (output document format)::
HL_OUTPUT: number
......@@ -303,6 +299,10 @@ HL_FORMAT_BBCODE: number
HL_FORMAT_PANGO: number
HL_FORMAT_ODT: number
Add additional stying information:
Injections: table
5. STEP BY STEP
-------------------------------------------------------------------------------
......@@ -392,10 +392,6 @@ Description: Add function names to keyword list
Features: Adds new keyword group based on a regex, defines OnStateChange,
uses AddKeyword
cpp_qt.lua, cpp_syslog.lua, cpp_wx.lua, java_library.lua
Description: *
Features: Adds and extends keyword groups based on lists and regexes
theme_invert.lua
Description: Invert colours of the original theme
Features: Modifies all color attributes of the theme script, uses Lua
......@@ -432,7 +428,7 @@ Description: Adds code folding for C style languages, Pascal, Lua and Ruby to
HTML output
Features: Uses DecorateLineBegin and DecorateLineEnd to add ID-spans to each
line.
Applies Decorate to each block delimiter to add onClick event
Applies Decorate to each code block delimiter to add onClick event
handlers.
Adds JavaScript with HeaderInjection and FooterInjection variables.
Inserts additional CSS styles with Injections variable.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment