Inside Markup Services

 

• Markup module
  • markupstring ($string, $virtp)
  • is_linkworthy ($string)
  • markspecials ($string)
  • htmlquote ($string)
  • freetextmarkup ($string)
  • markupfile ($fileh, $outfun)

Markup module

This module is the markup engine in charge of highlighting the syntactic components or otherwise interesting elements of a block.

markupstring ($string, $virtp)

Function markupstring returns $string after marking up some items deemed "interesting" (e-mail addresses, URLs, files, identifiers, ...).

1. $string

   a string to mark up

2. $virtp

   a string containing the HTML-path for the directory of files

   It is used to build a link to files, supposing they are located in this directory

This is a smaller version of sub markupfile meant for marking up the descriptions in source directory listings (see Local.pm).

is_linkworthy ($string)

Function is_linkworthy returns true if $string is in the identifier DB and seems to be used as an identifier (not just some word that happens to have been used as a variable name somewhere).

1. $string

   a string containing the symbol to check

The string must be long enough (to bar words like "of", "to" or "a"). Presently it must be at least 6 characters long. It looks like an identifier if it contains an underscore ("_") or a capitalized letter after the first character.

Some common names like README are rejected.

The symbol must also have been entered into the DB.

TO DO:

• DB check is not implemented. It could be through index->symreferences($string, $releaseid) or $index->symdeclarations($string, $releaseid) if we want to consider only declared identifiers.

markspecials ($string)

Function markspecials tags "special" characters in its argument with a NUL (\0).

1. $string

   a string to tag

This sub is called before editing (highlighting) the string argument so that we can later distinguish between original literal HTML special characters and those added as part of HTML tags.

htmlquote ($string)

Function htmlquote untags "special" characters in its argument and HTML-quote them.

1. $string

   a string to untag

This sub is called as the last step of editing (highlighting) before emitting the string as HTML stream. The originally literal special HTML characters are replaced by their entity name equivalent.

freetextmarkup ($string)

Function freetextmarkup creates links in its argument for URLs and e-mail addresses.

1. $string

   a string to edit

This sub is intended to create links in comments or otherwise free text.

markupfile ($fileh, $outfun)

Function markupfile is the edition driver.

1. $fileh

   a filehandle for the source file

2. $outfun

   a reference to a sub which outputs the HTML stream

The parser is repeatedly called to split the source file into homogeneous fragments which are highlighted by one of the preceding specialized support routines.

Sub &$outfun is called to output the HTML stream. Use of a subroutine allows to do the highlighting with markupfile in every context (single file display by source or dual file display by diff).