1  source-highlighting EMC langues in HTML documents
 2  =================================================
 3  
 4  I've created GNU source-highlight language definitions for G-code and
 5  halcmd to highlight .hal and .ngc files in asciidoc. .ini file
 6  highlighting works out of the box. All three need a bit of trickery to
 7  work cleanly for both html and pdf.
 8  
 9  Highlighting is for HTML output only at this point in time.  To have
10  PDF's highlighted, the file
11  /usr/share/texmf-texlive/tex/latex/listings/lstlang1.sty needs to be
12  extended to deal with ngc, hal and ini formats, and put into the build
13  directory so dblatex can find it.
14  
15  Highlighting halcmd, ini and ngc source in HTML is now integrated into
16  the documentation build process. tcl, python, sh etc keep working out
17  of the box.
18  
19  NB: source-highlight's mechanisms to find .lang and .map files is
20  very inflexible which is why the complete source language definition
21  directoy (/usr/share/source-highlight) needs to be replicated under 'local',
22  and a new lang.map generated in there (all language definitions are
23  relative to this directory, and include each other).
24  
25  Using ngc, hal and ini file snippets in your .txt files:
26  ========================================================
27  Copy this to the top of your txt file:
28  ----------------- snip ----------------
29  :ini: {basebackend@docbook:'':ini}
30  :hal: {basebackend@docbook:'':hal}
31  :ngc: {basebackend@docbook:'':ngc}
32  
33  // begin a listing of ini/hal/ngc files like so:
34  //[source,{ini}]
35  //[source,{hal}]
36  //[source,{ngc}]
37  ----------------- snip ----------------
38  
39  Adding or changing a langauage definition (.lang) file
40  ======================================================
41  
42  New language: just drop <name>.lang into this directory. The
43  source-highlight configuration will be rebuilt to include this
44  language. <name> then can be used in [source,{named}] listings. You
45  might need a conditional like
46  
47  :name: {basebackend@docbook:'':name}
48  
49  to prevent pdflatex formatting errors.
50  
51  Changing a language defintion: just edit the .lang file in this directory.
52  
53  Overruling definitons in the source-highlight standard language definitions:
54  
55  Copy the <language>.lang file from /usr/share/source-highlight into
56  this directory and edit as needed. The right things should happen on
57  build (including a massive initial rebuild ;-)
58  
59  
60  Building HTML examples in the this directory
61  ============================================
62  
63  To produce pdf and html samples, type 'make examples' .
64  
65  This should produce {ini-demo,hal-demo,ngc-demo}.{pdf,html} files in
66  the current directory, with proper highlighing of HTML only. PDF files
67  come out properly but have no highlighting.
68  
69  --------------------------------------------
70  
71  I found this tool very helpful for writing GNU source-highlight .lang
72  definitions:
73  
74  http://srchighliteide.sourceforge.net/
75  
76  Michael Haberler 3/2011