forked from andre-simon/highlight
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME_DE
1001 lines (720 loc) · 35.2 KB
/
README_DE
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
-------------------------------------------------------------------------------
--- HIGHLIGHT HANDBUCH ----- Version 3.41 --------------- November 2017 ---
-------------------------------------------------------------------------------
OSI Certified Open Source Software
English manual: README
INHALT
-------------------------------------------------------------------------------
1. UEBERSICHT
1.1 SINN UND ZWECK
1.2 FUNKTIONSLISTE
1.3 UNTERSTUETZTE PROGRAMMIER- UND AUSZEICHNUNGSSPRACHEN
2. GEBRAUCH UND OPTIONEN
2.1 SCHNELLE EINFUEHRUNG
2.2 CLI OPTIONEN
2.3 GUI OPTIONEN
2.4 EIN- UND AUSGABE
2.5 GNU SOURCE-HIGHLIGHT KOMPATIBILITAET
2.6 FORTGESCHRITTENE OPTIONEN
2.7 UMGEBUNGSVARIABLEN
3. KONFIGURATION
3.1 DATEIFORMAT
3.2 SPRACHDEFINITIONEN
3.3 REGULAERE AUSDRUECKE
3.4 FARBDEFINITIONEN
3.5 SCHLUESSELWORTGRUPPEN
3.6 PLUG-INS
3.7 DATEIZUORDNUNGEN
3.8 PFADE DER KONFIG-DATEIEN
4. HIGHLIGHT INTEGRIEREN
4.1 BEISPIELSKRIPTE
4.2 PANDOC
4.3 SWIG
4.4 TCL
4.5 SKRIPTE UND PLUG-INS FUER DRITTSOFTWARE
5. KOMPILIEREN UND INSTALLIEREN
5.1 VORKOMPILIERTE PAKETE
5.2 KOMPILIER-ABHAENGIGKEITEN
6. ENTWICKLERKONTAKT
1. UEBERSICHT
-------------------------------------------------------------------------------
Highlight konvertiert Sourcecode in XHTML, HTML, RTF, ODT, TeX, LaTeX, SVG,
BBCode, Pango Markup und Terminal Escape-Sequenzen mit farbiger Syntaxhervorhebung.
Sprachdefinitionen und Farbstile sind konfigurierbar.
1.1 SINN UND ZWECK
-------------------------------------------------------------------------------
Highlight wurde mit dem Ziel entworfen, einen flexiblen und einfach zu
bedienenden Syntaxhighlighter fuer mehrere Ausgabeformate anzubieten.
Statt hartkodierter Sprachbeschreibungen und Farbschemata sind alle wichtigen
Informationen in Konfigurationsskripten enthalten. Diese Lua-Skripte koennen
mit Plug-Ins angepasst und erweitert werden.
1.2 FUNKTIONSLISTE
-------------------------------------------------------------------------------
* Hervorhebung von Schluesselwoertern, Typbezeichnern, Strings, Zahlen,
Escapesequenzen, Operatoren, Praeprozessor-Direktiven und Kommentaren
* Farbige Ausgabe in HTML, XHTML, RTF, TeX, LaTeX, SVG, BBCode, Pango Markup und
Terminal-Escapesequenzen
* Speichern von Stylesheets wahlweise in separater Datei oder innerhalb der
Ausgabedatei (HTML, LaTeX, TeX, SVG)
* Alle Konfigurationsdateien sind Lua-Skripte
* Unterstuetzt Plug-In Skripte zur Anpassung von Sprachdefinitionen und Themes
* Syntax-Elemente werden als regelaere Ausdruecke oder als Stringlisten
beschrieben
* Erweiterbare Schluesselwort-Gruppen
* Erkennung mehrerer Sprachen innerhalb einer Datei
* Neuformatierung und Einrueckung von C, C++, C# und Java Code
* Umbrechen von langen Zeilen
* Anpassbare Ausgabe von Zeilennummern
1.3 UNTERSTUETZTE PROGRAMMIER- UND AUSZEICHNUNGSSPRACHEN
-------------------------------------------------------------------------------
Die Liste aller unterstuetzten Sprachen befindet sich in README_LANGLIST.
Das Kommando "highlight --list-scripts=langs" zeigt ebenfalls eine Liste aller
Sprachen und den verknuepften Dateiendungen.
2. GEBRAUCH UND OPTIONEN
-------------------------------------------------------------------------------
2.1 SCHNELLE EINFUEHRUNG
-------------------------------------------------------------------------------
Folgende Beispiele zeigen, wie man die hervorgehobene Ausgabe einer C++-Datei
namens main.cpp erzeugt:
- HTML ausgeben:
highlight -i main.cpp -o main.cpp.html
highlight < main.cpp > main.cpp.html --syntax cpp
Sie werden die HTML-Datei und die CSS-Datei highlight.css im aktuellen
Verzeichnis finden. Falls Sie Eingabe-Umleitung verwenden (siehe 2. Beispiel),
geben Sie den Typ der Programmiersprache mit --syntax an.
- HTML mit eingebetteter CSS Definition und Zeilennummerierung ausgeben:
highlight -i main.cpp -o main.cpp.html --include-style --line-numbers
- HTML mit direkter CSS-Formatierung ausgeben:
highlight -i main.cpp -o main.cpp.html --inline-css
- LaTeX mit Code-Formatierung im "horstmann"-Stil und dem Farbschema "Neon"
ausgeben:
highlight -O latex -i main.cpp -o main.cpp.tex --reformat horstmann --style neon
Folgende Ausgabeformate koennen mit --out-format bestimmt werden:
html: HTML5 (Standard)
xhtml: XHTML 1.1
tex: Plain TeX
latex: LaTeX
rtf: RTF
odt: OpenDocument Text (Flat XML)
svg: SVG
bbcode: BBCode
pango: Pango markup
ansi: Terminal 16 color escape codes
xterm256: Terminal 256 color escape codes
truecolor: Terminal 16m color escape codes
- 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
- Ausgabeverzeichnis definieren:
highlight -d some/target/dir/ *.cpp *.h
2.2 CLI OPTIONEN
-------------------------------------------------------------------------------
Die Kommandozeilenversion von highlight bietet folgende Optionen:
USAGE: highlight [OPTIONS]... [FILES]...
General options:
-B, --batch-recursive=<wc> convert all matching files, searches subdirs
(Example: -B '*.cpp')
-D, --data-dir=<directory> set path to data directory
--config-file=<file> set path to a lang or theme file
-d, --outdir=<directory> name of output directory
-h, --help print this help
-i, --input=<file> name of single input file
-o, --output=<file> name of single output file
-P, --progress print progress bar in batch mode
-q, --quiet supress progress info in batch mode
-S, --syntax=<type> specify type of source code
-v, --verbose print debug info
--force generate output if input syntax is unknown
--list-scripts=<type> list installed scripts
<type> = [langs, themes, plugins]
--plug-in=<script> execute Lua plug-in script; repeat option to
execute multiple plug-ins
--plug-in-param=<value> set plug-in input parameter
--print-config print path configuration
--print-style print stylesheet only (see --style-outfile)
--skip=<list> ignore listed unknown file types
(Example: --skip='bak;c~;h~')
--start-nested=<lang> define nested language which starts input
without opening delimiter
--stdout output to stdout (batch mode, --print-style)
--validate-input test if input is text, remove Unicode BOM
--version print version and copyright information
Output formatting options:
-O, --out-format=<format> output file in given format
<format>=[html, xhtml, latex, tex, odt, rtf,
ansi, xterm256, truecolor, bbcode, pango, svg]
-c, --style-outfile=<file> name of style file or print to stdout, if
'stdout' is given as file argument
-e, --style-infile=<file> to be included in style-outfile (deprecated)
use a plug-in file instead
-f, --fragment omit document header and footer
-F, --reformat=<style> reformats and indents output in given style
<style> = [allman, banner, gnu,
horstmann, java, kr, linux, mozilla, otbs, vtk,
stroustrup, whitesmith, google, pico, lisp]
-I, --include-style include style definition in output file
-J, --line-length=<num> line length before wrapping (see -V, -W)
-j, --line-number-length=<num> line number width incl. left padding (default: 5)
-k, --font=<font> set font (specific to output format)
-K, --font-size=<num?> set font size (specific to output format)
-l, --line-numbers print line numbers in output file
-m, --line-number-start=<cnt> start line numbering with cnt (assumes -l)
-s, --style=<style> set colour style (theme)
-t, --replace-tabs=<num> replace tabs by <num> spaces
-T, --doc-title=<title> document title
-u, --encoding=<enc> set output encoding which matches input file
encoding; omit encoding info if set to NONE
-V, --wrap-simple wrap lines after 80 (default) characters w/o
indenting function parameters and statements
-W, --wrap wrap lines after 80 (default) characters
--wrap-no-numbers omit line numbers of wrapped lines
(assumes -l)
-z, --zeroes pad line numbers with 0's
--delim-cr set CR as end-of-line delimiter (MacOS 9)
--keep-injections output plug-in injections in spite of -f
--kw-case=<case> change case of case insensitive keywords
<case> = [upper, lower, capitalize]
--no-trailing-nl omit trailing newline
--no-version-info omit version info comment
(X)HTML output options:
-a, --anchors attach anchor to line numbers
-y, --anchor-prefix=<str> set anchor name prefix
-N, --anchor-filename use input file name as anchor prefix
-C, --print-index print index with hyperlinks to output files
-n, --ordered-list print lines as ordered list items
--class-name=<name> set CSS class name prefix;
omit class name if set to NONE
--inline-css output CSS within each tag (verbose output)
--enclose-pre enclose fragmented output with pre tag
(assumes -f)
LaTeX output options:
-b, --babel disable Babel package shorthands
-r, --replace-quotes replace double quotes by \dq{}
--beamer adapt output for the Beamer package
--pretty-symbols improve appearance of brackets and other symbols
RTF output options:
--page-color include page color attributes
-x, --page-size=<ps> set page size
<ps> = [a3, a4, a5, b4, b5, b6, letter]
--char-styles include character stylesheets
SVG output options:
--height set image height (units allowed)
--width set image width (see --height)
GNU source-highlight compatibility options:
--doc create stand alone document
--no-doc cancel the --doc option
--css=filename the external style sheet filename
--src-lang=STRING source language
-t, --tab=INT specify tab length
-n, --line-number[=0] number all output lines, optional padding
--line-number-ref[=p] number all output lines and generate an anchor,
made of the specified prefix p + the line
number (default='line')
--output-dir=path output directory
--failsafe if no language definition is found for the
input, it is simply copied to the output
2.3 GUI OPTIONEN
-------------------------------------------------------------------------------
Die graphische Oberflaeche bietet eine Teilmenge der CLI-Funktionen. Sie enthaelt
eine dynamische Vorschau der sichtbaren Ausgabe. Auf der Projekt-Webseite finden
Sie Screenshots und Screencasts.
Wird highlight-gui mit der Option --portable gestartet, speichert es die
Einstellungen im Programmverzeichnis (anstatt zB. die Registry zu benutzen).
2.4 EIN- UND AUSGABE
-------------------------------------------------------------------------------
Wenn kein Dateiname mit --input bzw. --output angegeben wird, benutzt highlight
stdin bzw. stdout fuer die Ein- und Ausgabe.
Wird die Eingabedatei nicht direkt auf der Kommandozeile als Argument bzw. mit
--input angegeben, kann Highlight die passende Sprachinformation nicht
automatisch anhand der Dateiendung bestimmen. Lediglich einige Skriptsprachen
werden anhand des Shebangs in der ersten Zeile erkannt.
Mit der Option --syntax muss dann der Typ der Datei vom Benutzer angegeben
werden (das Argument ist normalerweise die fuer die Programmiersprache uebliche
Dateierweiterung).
Beispiel: Wenn Sie eine Python-Datei konvertieren wollen, muss highlight die
Sprachdefinition py.lang einlesen. Das korrekte Argument fuer --syntax ist
also "py".
highlight test.py # Option --syntax nicht noetig
highlight < test.py --syntax py # --syntax muss angegeben werden
cat test.py | highlight --syntax py
Sollte es mehrere Dateierweiterungen fuer Dateien einer Programmiersprache
geben (wie z.B. C, cc, cpp, h bei C++), werden diese in der Datei
$CONF_DIR/filetypes.conf einer Sprachdefinition zugewiesen.
Wenn mehrere Eingabedateien an Highlight uebergeben werden oder --batch-recursive
gesetzt ist, wechselt das Tool in den Batch-Modus. In diesem Modus werden die
Ausgabedateien unter dem Namen der Eingabedateien gespeichert, zusaetzlich wird
die Dateierweiterung des gewaehlten Ausgabeformats angehangen.
Sollte es in den Eingabeverzeichnissen Dateien mit identischem Namen geben, so
werden diese Ausgabedateien mit ihrem Quellverzeichnis als Praefix ausgegeben.
Die --outdir Option ist im Batch Modus besonders nuetzlich. In Skripten sollte
--quiet angegeben werden, um die Geschwindigkeit der Verarbeitung zu erhoehen.
HTML, TeX, LaTeX und SVG Ausgabe:
--------------------------------
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.
Name und Pfad des Stylesheets werden mit --style-outfile bestimmt.
Wenn --outdir definiert ist, wird auch das Stylesheet im angegebenen
Ausgabeverzeichnis gespeichert.
Mit --include-style fuegt Highlight die Formatierungsangaben direkt in die
Ausgabedokumente ein, statt einen Verweis auf externe Stylesheets zu setzen.
Der Verweis auf externe Dateien hat den Vorteil, die Formatierung an einer
zentralen Stelle verwalten zu koennen, auf die alle Ausgabedokumente verweisen.
Mit --style-infile kann eine Datei mit zusaetzlichen Formatierungsangaben in
die Ausgabedateien eingebunden werden, welche die vorgegebene highlight-
Formatierung erweitert oder ueberschreibt.
Hinweis: Ein Plug-In Skript ist die bessere Methode das Styling anzupassen.
Terminal-Ausgabe:
--------------------
Da es nur wenige Farben zur ANSI-Ausgabe im Terminal gibt, existiert nur ein
hartkodiertes Farbschema fuer --out-format=ansi. Daher sollte nach Moeglichkeit
--out-format=xterm256 verwendet werden, um eine Ausgabe in 256 Farben zu erhalten.
Der 256 Farb-Modus wird z.B. von xterm, rxvt und Putty unterstuetzt.
Neuere Terminal-Emulatoren unterstuetzen auch 16 Millionen Farben, dies wird mit
--out-format=truecolors aktiviert.
highlight --out-format=ansi <inputfile> | less -R
highlight --out-format=xterm256 <inputfile> | less -R
Text-Ausgabe:
-------------
Wird als Sprachdefinition txt angegeben, findet keine Syntaxhervorhebung statt.
highlight -S txt --out-format=latex README > readme.tex
Beispiele:
----------
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
/home/you/html_code.
highlight -out-format=latex * --outdir /home/you/latex_code/
Dieses Kommando konvertiert alle Dateien in LaTeX, und speichert sie in
/home/you/latex_code/.
highlight --stdout -s seashell --print-style
Dieses Kommando gibt nur die CSS-Informationen des angegebenen Stils (hier:
Seashell) nach stdout aus.
2.5 GNU SOURCE-HIGHLIGHT KOMPATIBILITAET
-------------------------------------------------------------------------------
Die Kommandozeilenschnittstelle ueberschneidet sich zu einem grossen Teil mit
source-highlight (http://www.gnu.org/software/src-highlite/).
Diese highlight-Optionen haben dieselbe Bedeutung wie bei source-highlight:
--input, --output, --help, --version, --out-format, --title, --data-dir,
--verbose, --quiet
Diese Optionen wurden hinzugefuegt, um die Kompatibilitaet zu verbessern:
--css, --doc, --failsafe, --line-number, --line-number-ref, --no-doc, --tab,
--output-dir, --src-lang
Die obigen Optionen bilden eine gemeinsame Highlighter-Schnittstelle fuer
Skripte, Plugins etc.
2.6 FORTGESCHRITTENE OPTIONEN
-------------------------------------------------------------------------------
Parsen von Binaerdaten vermeiden
--------------------------------
Wird highlight mit unbekannten Eingabedaten aufgerufen, verhindert
--validate-input die Verarbeitung von binaeren Daten.
Dieser Schalter fuehrt zu einem Vergleich der Datei-Header mit einer Liste von
"Magic Numbers". Wenn ein Binaer-Typ erkannt wird, bricht highlight die
Verarbeitung mit einer Fehlermeldung ab.
Mit --validate-input wird zusaetzlich der UTF-8 BOM in der Ausgabe unterdrueckt.
Hervorhebung von eingebettetem Code ohne oeffnenden Delimiter
-------------------------------------------------------------
Wenn eine Datei mit eingebettetem Code ohne einen fuer diese Syntax ueblichen
einleitenden Delimiter beginnt, kann mit der --start-nested Option in diese
Sprache gewechselt werden. Dies kann bei LuaTeX Dateien noetig sein:
highlight luatex.tex --latex --start-nested=inc_luatex
Die inc_luatex Definition ist eine Lua-Beschreibung mit TeX Kommentaren.
Neue Konfigurationsskripte testen:
----------------------------------
Die Option --config-file ermoeglicht es, neue Skripte vor der Installation zu
testen. Die Datei muss eine lang- oder theme-Datei sein.
highlight --config-file xxx.lang --config-file yyy.theme -I
Sprachdefinitionen debuggen:
----------------------------
Benutzen Sie --verbose, um Lua- und Syntax-Daten anzuzeigen.
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)
----------------------------
Starten Sie highlight-gui.exe mit der --portable Option, damit die
Konfiguration in Textdateien und nicht in der Registry gespeichert wird.
2.7 UMGEBUNGSVARIABLEN
-------------------------------------------------------------------------------
Die Kommandozeilenversion beruecksichtigt folgende Variablen:
HIGHLIGHT_DATADIR: setzt den Pfad zum Konfigurationsverzeichnis
HIGHLIGHT_OPTIONS: kann Kommandozeilenoptionen enthalten, aber keine Pfade zu
Eingabedateien
3. KONFIGURATION
-------------------------------------------------------------------------------
3.1 DATEIFORMAT
-------------------------------------------------------------------------------
Die Konfigurationsdateien sind Lua Skripte. Deutsche Einfuehrung in die Syntax:
http://www.fh-wedel.de/~si/seminare/ws09/Ausarbeitung/09.lua/lua1.htm
Das vollstaendige Lua-Handbuch befindet sich hier:
http://www.lua.org/manual/5.1/manual.html
Folgende Syntax-Elemente genuegen, um die Skripte anzupassen:
Wertzuweisung an Variablen:
name = value
(Variablen haben keinen Typ, nur Werte haben einen)
Strings:
string1="string-Literal mit Escape-Sequenzen: \n"
string2=[[Raw String ohne Escape-Sequenzen]]
Wenn ein Raw-String mit "[" beginnt oder mit "]" endet, muss die Klammer mit
Leerzeichen von den Begrenzern getrennt werden, um Syntaxfehler zu vermeiden.
Highlight entfernt diese Leerzeichen beim Einlesen.
Ist der String ein regulaerer Ausdruck mit einem Ausdruck wie [[:space:]],
muss der Stringbegrenzer mit einem "Fueller" verwendet werden:
[=[ regex string ]=]
Kommentare:
-- Einzeiliger Kommentar
--[[ Blockkommentar ]]
Arrays:
array = { first=1, second="2", 3, { 4,5 } }
Arrays koennen Variablen enthalten und geschachtelt sein.
3.2 SPRACHDEFINITIONEN
-------------------------------------------------------------------------------
Eine Sprachdefinition beschreibt die Elemente einer Programmiersprache, die
durch verschiedene Farben und Schrifttypen hervorgehoben werden.
Die Datei muss in langDefs/ unter folgendem Namen gespeichert werden:
<uebliche Erweiterung der Sourcecodedateien>.lang
Beispiele: PHP -> php.lang, Java -> java.lang
Sollte es mehrere gebrauechliche Erweiterungen geben, werden diese in der Datei
filetypes.conf einer Sprachdefinition zugeordnet.
Syntax-Elemente:
Keywords = { Id, List|Regex, Group? }
Id: Integer, ID der Schluesselwortgruppe (Werte 1-4, die mehrfach verwendet
werden koennen)
List: Liste, Auflistung von Schluesselwoertern
Regex: String, Regulaerer Ausdruck
Group: Integer, Capturing Group ID der Regex, bestimmt den Teil des gefundenen
Ausdrucks, der als Schluesselwort hervorgehoben werden soll (optional,
wenn nicht gesetzt wird der Match mit der hoechsten Group-ID zurueck-
gegeben (gezaehlt wird von links nach rechts))
Comments = { {Block, Nested?, Delimiter} }
Block: Boolean, true wenn der Kommentar ein Blockkommentar ist
Nested: Boolean, true wenn der Blockkommentar verschachtelt werden darf (optional)
Delimiter: Liste, enthaelt Regex der oeffnenden Begrenzer (Zeilenkommentar) oder
Regex des oeffnenden und des schliessenden Begrenzers (Blockkommentar)
Strings = { Delimiter|DelimiterPairs={Open, Close, Raw?}, Escape?, Interpolation?,
RawPrefix?, AssertEqualLength? }
Delimiter: String, Regulaerer Ausdruck der Begrenzer
DelimiterPairs: Liste, enthaelt Ausdruecke der oeffnenden und der schliessenden
Begrenzer wenn diese nicht gleich sind und optional ein Raw-
String Flag
Escape: String, Regulaerer Ausdruck fuer Escapsesequenzen (optional)
Interpolation: String, Regulaerer Ausdruck fuer Interpolation (optional)
RawPrefix: String, definiert Raw String Prefix (optional)
AssertEqualLength: Boolean, True wenn die Begrenzer gleich lang sein muessen
PreProcessor = { Prefix, Continuation? }
Prefix: String, Regulaerer Ausdruck der oeffnenden Begrenzer
Continuation: String, Definiert Fortsetzungsindikator (optional)
NestedSections = {Lang, Delimiter= {} }
Lang: String, Name der eingebetteten Sprache
Delimiter: Liste, Ausdruecke der oeffnenden und der schliessenden Begrenzer
Description: String, Beschreibung der Syntax
Digits: String, Regulaerer Ausdruck fuer Zahlenliterale (optional)
Identifiers: String, Regulaerer Ausdruck fuer Bezeichner (optional)
Operators: String, Regulaerer Ausdruck fuer Operatoren
EnableIndentation: Boolean, True wenn Syntax formatiert und eingerueckt werden kann
IgnoreCase: Boolean, True wenn Sprache nicht case-sensitive ist
Globale Variablen:
Die folgenden Variablen sind in einer Sprachbeschreibung verfuegbar:
HL_LANG_DIR: Verzeichnis der Sprachdefinitionen (Parameter der Lua dofile-Funktion)
Identifiers: Default regex fuer Bezeichner
Digits: Default regex fuer Zahlenliterale
Diese Integer-Variablen beschreiben die internen Zustaende des highlight-Parsers:
HL_STANDARD
HL_STRING
HL_NUMBER
HL_LINE_COMMENT
HL_BLOCK_COMMENT
HL_ESC_SEQ
HL_PREPROC
HL_PREPROC_STRING
HL_OPERATOR
HL_INTERPOLATION
HL_LINENUMBER
HL_KEYWORD
HL_STRING_END
HL_LINE_COMMENT_END
HL_BLOCK_COMMENT_END
HL_ESC_SEQ_END
HL_PREPROC_END
HL_OPERATOR_END
HL_KEYWORD_END
HL_INTERPOLATION_END
HL_EMBEDDED_CODE_BEGIN
HL_EMBEDDED_CODE_END
HL_IDENTIFIER_BEGIN
HL_IDENTIFIER_END
HL_UNKNOWN
HL_REJECT
Die Funktion OnStateChange:
Dieser Hook wird bei Zustandsuebergaengen des Parsers aufgerufen (z.B. beim
Wechsel von HL_STANDARD zu HL_KEYWORD wenn ein Schluesselwort erkannt wurde).
Mit dieser Funktion kann der neue Zustand angepasst werden, oder es koennen
Syntax-Elemente wie Keyword-Listen erweitert werden.
OnStateChange(oldState, newState, token, kwGroupID)
Hook Event: Zustandswechsel des Parsers
Parameters: oldState: bisheriger Zustand
newState: geplanter neuer Zustand
token: das Token welches den Wechsel ausgeloest hat
kwGroupID: Wenn newState = HL_KEYWORD, enthaelt dieser Parameter
die Gruppen-ID
Returns: den korrekten Zustand zum fortfahren ODER HL_REJECT
HL_REJECT wird dann zurueckgegeben, wenn das Token und der erkannte Zustand
verworfen werden sollen; das erste Zeichzen von Token wird dann ausgegeben und
als "oldState" hervorgehoben.
Beispiele:
function OnStateChange(oldState, newState, token)
if token=="]]" and oldState==HL_STRING and newState==HL_BLOCK_COMMENT_END then
return HL_STRING_END
end
return newState
end
Diese Funktion loest ein Parsing-Problem in Lua, weil der Begrenzer "]]" Kommentare
und Strings abschliessen kann.
function OnStateChange(oldState, newState, token)
if token=="'" and oldState==HL_NUMBER and newState==HL_STRING then
return HL_NUMBER
end
return newState
end
Dieser Hook ermoeglicht das korrekte Parsen von C++14 Zahl-Literalen.
Weitere Funktionen sind in README_PLUGINS beschrieben.
Beispiel:
---------
Description="C and C++"
Keywords={
{ Id=1,
List={"goto", "break", "return", "continue", "asm", "case", "default",
-- [..]
}
},
-- [..]
}
Strings = {
Delimiter=[["|']],
RawPrefix="R",
}
Comments = {
{ Block=true,
Nested=false,
Delimiter = { [[\/\*]], [[\*\/]] } },
{ Block=false,
Delimiter = { [[//]] } }
}
IgnoreCase=false
PreProcessor = {
Prefix=[[#]],
Continuation="\\",
}
Operators=[[\(|\)|\[|\]|\{|\}|\,|\;|\.|\:|\&|\<|\>|\!|\=|\/|\*|\%|\+|\-|\~]]
EnableIndentation=true
3.3 REGULAERE AUSDRUECKE
-------------------------------------------------------------------------------
Die Datei README_REGEX beschreibt alle unterstuetzten Ausdruecke.
3.4 FARBDEFINITIONEN
-------------------------------------------------------------------------------
Farbdefinitionen legen die Formatierung der Sprachelemente fest, die in den
Sprachdefinitionen beschrieben wurden.
Die Dateien muessen mit der Endung .theme in themes/ gespeichert werden.
Mit der --style (-s) Option wird das Farbschema angewandt.
Formatattribute:
Attributes = {Colour, Bold?, Italic?, Underline? }
Colour: String, Farbe in Hex-Notation ("#rrggbb")
Bold: Boolean, True wenn Font bold sein soll (optional)
Italic: Boolean, True wenn Font kursiv sein soll (optional)
Underline: Boolean, True wenn Font unterstrichen sein soll (optional)
Theme-Elemente:
Description: String, Theme-Beschreibung
Default = Attributes (Farbe des nicht hervorgehobenen Texts)
Canvas = Attributes (Hintergrundfarbe)
Number = Attributes (Formatierung von Zahlen)
Escape = Attributes (Formatierung von Escape-Sequenzen)
String = Attributes (Formatierung von Strings)
Interpolation = Attributes (Formatierung von Interpolationen)
PreProcessor = Attributes (Formatierung von Praeprozessor-Direktiven)
StringPreProc = Attributes (Formatierung von Strings in
Praeprozessor-Direktiven)
BlockComment = Attributes (Formatierung von Blockkommentaren)
LineComment = Attributes (Formatierung von Zeilenkommentaren)
LineNum = Attributes (Formatierung von Zeilennummern)
Operator = Attributes (Formatierung von Operatoren)
Keywords= {
Attributes1,
Attributes2,
Attributes3,
Attributes4,
}
AttributesN: Liste, Formatierung von Schluesselwoertgruppen. Es sollten
mindestens vier Elemente angegeben werden, um mit der Anzahl
von Schluesselwortgruppen in den Sprachdefinitionen
uebereinzustimmen.
Beispiel:
Default = { Colour="#000000" }
Canvas = { Colour="#ffffff" }
Number = { Colour="#000000" }
Escape = { Colour="#bd8d8b" }
String = { Colour="#bd8d8b" }
StringPreProc = { Colour="#bd8d8b" }
BlockComment = { Colour="#ac2020", Italic=true }
PreProcessor = { Colour="#000000" }
LineNum = { Colour="#555555" }
Operator = { Colour="#000000" }
LineComment = BlockComment
Keywords = {
{ Colour= "#9c20ee", Bold=true },
{ Colour= "#208920" },
{ Colour= "#0000ff" },
{ Colour= "#000000" },
}
3.5 SCHLUESSELWORTGRUPPEN
-------------------------------------------------------------------------------
Sie koennen eigene Schluesselwort-Gruppen festlegen und jeder Gruppe eine eigene
Formatierung zuweisen. Das ist nuetzlich wenn Sie z.B. Bibliotheksfunktionen,
Makros oder Konstanten gesondert hervorheben moechten.
Eine Gruppe wird in zwei Schritten definiert:
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:
Keywords= {
--Stil als fuenften Eintrag hinterlegen:
{ Colour= "#ff0000", Bold=true },
}
Es wird empfohlen, eigene Keyword-Gruppen in Plugin-Skripten zu definieren,
um keine Original-Dateien zu veraendern.
Weitere Infos finden sich im cpp_qt.lua Beispiel-Plugin sowie in README_PLUGINS.
3.6 PLUG-INS
-------------------------------------------------------------------------------
Die --plug-in Option erwartet den Pfad eines Lua Skripts, das Elemente einer
Sprachdefinition oder eines Themes ueberschreibt oder erweitert.
Mit Hilfe dieser Plugins kann die Ausgabe angepasst werden, ohne installierte
Konfigurations-Dateien zu aendern.
Man kann mehrere Plugins anwenden, indem die --plug-in Option wiederholt
angegeben wird.
Siehe README_PLUGINS um mehr darueber zu erfahren.
3.7 DATEIZUORDNUNGEN
-------------------------------------------------------------------------------
In filetypes.conf werden Dateizuordnungen und Shebang-Definitionen eingetragen.
Eine Konfiguration ist nur dann zwingend notwendig, wenn es mehrere Dateiendungen
fuer eine Syntax gibt oder eine Endung nicht eindeutig zugewiesen werden kann.
Ansonsten wird die Syntax geladen, deren Name mit der Dateiendung der Eingabedatei
uebereinstimmt.
Format:
FileMapping={
{ Lang, Filenames|Extensions|Shebang },
}
Lang: String, Name der Sprachdefinition
Filenames: Liste, enthaelt alle Dateinamen, die "Lang" zugeordnet werden
Extensions: Liste, enthaelt alle Dateiendungen, die "Lang" zugeordnet werden
Shebang: String, Regulaerer Ausdruck der mit der ersten Zeile der Eingabe
verglichen wird
Verhalten der Software bei mehrdeutigen Endungen:
- CLI: die erste eingetragene Verknuepfung wird angewandt
- GUI: eine Syntax-Auswahl wird angezeigt
Tragen Sie neue Dateiendungen auch in gui_files/ext/fileopenfilter.conf ein,
damit diese im GUI-Dateiauswahldialog als Filter angezeigt werden.
3.8 PFADE DER KONFIG-DATEIEN
-------------------------------------------------------------------------------
Konfigurationsskripte werden in folgenden Verzeichnissen gesucht:
1. ~/.highlight/
2. Wert der Umgebungsvariablen HIGHLIGHT_DATADIR
3. benutzerdefiniertes Verz., definiert mit --data-dir (deprecated)
4. /usr/share/highlight/
5. /etc/highlight/ (wegen filetypes.conf)
6. aktuelles Arbeitsverzeicnnis (Fallback)
Es wird erwartet, dass folgende Unterverzeichnisse die entsprechenden Skripte
enthalten:
-langDefs: *.lang
-themes: *.theme
-plugins: *.lua
Eine eigene filetypes.conf kann direkt in in ~/.highlight/ gespeichert werden.
Diese Suchreihenfolge vereinfacht die Erweiterung und Anpassung bestehender
Skripte, ohne vorinstallierte Dateien umkopieren zu muessen.
4. HIGHLIGHT EINBETTEN
-------------------------------------------------------------------------------
4.1 BEISPIELSKRIPTE
-------------------------------------------------------------------------------
Im extras/ Unterverzeichnis befinden sich Beispielskripte in PHP, Perl und
Python, die highlight aufrufen und die Ausgabe als String auswerten. Diese
Skripte koennen als Ausgangspunkt fuer neue Erweiterungen genutzt werden.
4.2 PANDOC
-------------------------------------------------------------------------------
PP Makros und eine Anleitung dazu liegen in extras/pandoc.
4.3 SWIG
-------------------------------------------------------------------------------
Eine SWIG Interface-Datei befindet sich in extras/swig.
Installationshinweise stehen in README_SWIG, Beispiele sind in Perl, PHP und
Python vorhanden.
4.4 TCL
-------------------------------------------------------------------------------
Eine TCL-Erweiterung befindet sich in /extras/tcl.
Installationshinweise stehen in README_TCL.
4.5 SKRIPTE UND PLUG-INS FUER DRITTSOFTWARE
-------------------------------------------------------------------------------
Im extras/web_plugins Unterverzeichnis befinden sich einige Plugins, die
Highlight in Webanwendungen integrieren:
-DokuWiki
-MovableType
-Wordpress
-Serendipity
Andere Anwendungen von highlight sind auf andre-simon.de aufgelistet.
Diese Seite verweist auf unterschiedliche Projekte die highlight integrieren,
z.B. Webgit, Evolution, Inkscape, Ranger, ...).
5. KOMPILIEREN UND INSTALLIEREN
-------------------------------------------------------------------------------
5.1 VORKOMPILIERTE PAKETE
-------------------------------------------------------------------------------
Highlight ist in ISO C++ geschrieben. Es existieren folgende Pakete:
- UNIX Kommandozeilen- und GUI-Anwendung
- Windows Kommandozeilen- und GUI-Anwendung
- Statische/dynamische Bibliothek
Auf der Website www.andre-simon.de sind Links auf vorkompilierte Pakete fuer
weitere Betriebssysteme vorhanden (z.B. Debian, Arch Linux, Ubuntu, Darwin,
FreeBSD).
Auf der Website sind immer die aktuellsten Source-Pakete (upstream) verfuegbar.
Source tarball
Windows und MacOS executables
http://www.andre-simon.de
Arch Linux
http://www.archlinux.org/packages/community/i686/highlight/
Debian GNU/Linux
https://packages.debian.org/search?keywords=highlight
Fedora
http://koji.fedoraproject.org/koji/packageinfo?packageID=2044
FreeBSD
http://www.freshports.org/textproc/highlight/
Gentoo Portage
https://packages.gentoo.org/packages/app-text/highlight
Mac OS X
http://braumeister.org/formula/highlight
Slackware
http://sotirov-bg.net/slackpack/search.cgi?q=highlight
SuSE
http://packman.links2linux.de/package/highlight
Ubuntu
http://packages.ubuntu.com/oneiric/allpackages
Windows Chocolatey
https://chocolatey.org/packages/highlight
In INSTALL befinden sich weitere Informationen zu Paketinhalt und Installation.
5.2 KOMPILIER-ABHAENGIGKEITEN
-------------------------------------------------------------------------------
Highlight kompiliert zumindest mit gcc und clang. Zum Kompilieren sind Boost
Header-Pakete und Lua5.x/LuaJit Development-Pakete noetig.
Die optionale GUI benoetigt Qt5 Development-Pakete.
Im Makefile finden Sie weitere Informationen.
6. ENTWICKLERKONTAKT
-------------------------------------------------------------------------------
Andre Simon
http://www.andre-simon.de
sf.net Projekt mit SVN Repository, Download Mirror, Bugtracker, Foren:
http://sourceforge.net/projects/syntaxhighlight/
Github Projekt mit Git Repository, Bugtracker: