# Highlight PP-Macros Usage Example

# External File Examples

Through the `!HighlightFile` macro, external source code files can be passed to Highlight and the HTML output injected into the final document.

## First Example

We’ll import and syntax highlight the PureBASIC example file “`example.pb`” without passing any extra options to Highlight.

macro used:

    !HighlightFile(example.pb)(purebasic)

output result:

    ; ==============================================================================
    ;                             PureBASIC Example File
    ; ==============================================================================
    ; "example.pb" | PureBASIC 5.61

    For i=5 To 1 Step -1
      TEXT$ = "Iteration number: " + Str(i) + ~"\n\nDo you wish to continue?"
      UserChoice = MessageRequester("Countdown Dialog", TEXT$, #PB_MessageRequester_YesNo | #PB_MessageRequester_Info)
      If UserChoice = #PB_MessageRequester_No
        Break
      EndIf
    Next

## Second Example

Now we’ll highlight the same external file, this time passing some extra options to Highlight in order to show line numbers.

macro used:

    !HighlightFile(example.pb)(purebasic)(--line-numbers --line-number-length=2)

output result:

     1 ; ==============================================================================
     2 ;                             PureBASIC Example File
     3 ; ==============================================================================
     4 ; "example.pb" | PureBASIC 5.61
     5
     6 For i=5 To 1 Step -1
     7   TEXT$ = "Iteration number: " + Str(i) + ~"\n\nDo you wish to continue?"
     8   UserChoice = MessageRequester("Countdown Dialog", TEXT$, #PB_MessageRequester_YesNo | #PB_MessageRequester_Info)
     9   If UserChoice = #PB_MessageRequester_No
    10     Break
    11   EndIf
    12 Next

# Code Block Examples

With the `!Highlight` macro it’s possible to invoke Highlight on code blocks inside the document.

Let’s apply the `!Highlight` macro to a block of PureBASIC code, with some extra Highlight options for line numbering.

macro used:

    !Highlight(purebasic)(-l -j 2)
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    ; PureBASIC 5.61 Example (inside markdown document)

    Truth$ = "André Simon's Highlight is 100% cool!" ; Undeniable!

    ; Let's build an Ascii frame for this truthful statement:
    ; =======================================================

    FrameCenter$ = "| " + Truth$ + ~" |\n"
    FrameBorder$ = LSet("+", Len(FrameCenter$)-2, "-") + "+"
    FramedTruth$ = FrameBorder$ + #LF$ + FrameCenter$ + FrameBorder$

    ; Now by printing FramedTruth$ you'll get:
    ; +---------------------------------------+
    ; | André Simon's Highlight is 100% cool! |
    ; +---------------------------------------+

    Debug FramedTruth$
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

output result:

     1 ; PureBASIC 5.61 Example (inside markdown document)
     2
     3 Truth$ = "André Simon's Highlight is 100% cool!" ; Undeniable!
     4
     5 ; Let's build an Ascii frame for this truthful statement:
     6 ; =======================================================
     7
     8 FrameCenter$ = "| " + Truth$ + ~" |\n"
     9 FrameBorder$ = LSet("+", Len(FrameCenter$)-2, "-") + "+"
    10 FramedTruth$ = FrameBorder$ + #LF$ + FrameCenter$ + FrameBorder$
    11
    12 ; Now by printing FramedTruth$ you'll get:
    13 ; +---------------------------------------+
    14 ; | André Simon's Highlight is 100% cool! |
    15 ; +---------------------------------------+
    16
    17 Debug FramedTruth$

# Adding A Color Theme

Now we’ll import Highlight’s `edit-purebasic` theme into the document.

macro used:

    !HighlightInlineTheme(edit-purebasic)

… which will inject the following code in the HTML document’s source:

    <style type="text/css">
    /* Style definition file generated by highlight 3.39, http://www.andre-simon.de/ */
    /* highlight theme: PureBASIC */
    body.hl { background-color:#ffffdf; }
    pre.hl  { color:#000000; background-color:#ffffdf; font-size:10pt; font-family:'Courier New',monospace;}
    .hl.num { color:#000000; }
    .hl.esc { color:#0080ff; }
    .hl.str { color:#0080ff; }
    .hl.pps { color:#0080ff; }
    .hl.slc { color:#00aaaa; }
    .hl.com { color:#00aaaa; }
    .hl.ppc { color:#924b72; }
    .hl.opt { color:#000000; }
    .hl.ipl { color:#0080ff; }
    .hl.lin { color:#808080; }
    .hl.kwa { color:#006666; font-weight:bold; }
    .hl.kwb { color:#924b72; }
    .hl.kwc { color:#006666; }
    .hl.kwd { color:#0080ff; }

    </style>

Enjoy…