txt[ Glyph was created wih extensibility in mind. You can freely extend &[glang] by creating or overriding macros, to do whatever you like. Macro definitions are written in pure Ruby code and placed in @.rb@ files within the @lib/macros/@ folder of your project. box[Alternative Ways to Define Macros| You can also define macros: * inside your document, using the %>[macro:]. * Using the %>[include] specifying the path to an @.rb@ file containing macro definitions stored in the @lib/@ directory (useful especially when =>[#lite_mode|compiling single Glyph files]). ] This is the source code of a fairly simple macro used to format a note: ] highlight[=ruby| macro :note do %{<div class="#{@name}"><span class="note-title">#{@name.to_s.capitalize}</span> #{@value} </div>} end =] txt[ The @macro@ method takes a single @Symbol@ or @String@ parameter, corresponding to the name of the macro. In this case, the entire block (or _body_ of the macro) is a @String@ corresponding to what we want the macro to evaluate to: a @<div>@ tag containing a note. The body of the macro is evaluated in the context of the class[Glyph::Macro] class, therefore its instance variables (like code[@name] or code[@value]) can be used directly. box[Why using code[@name] instead of just "note"?| For the @note@ macro, it absolutely makes no difference. However, by using code[@name] it is possible to re-use the same code for the @tip@, @important@ and @caution@ macros as well, which are in fact only aliases of the @note@ macro. ] The following table lists all the instance variables that can be used inside macros: ] table[ tr[ th[Variable] th[Description] ] tr[ td[code[@node]] td[ txt[ A class[Glyph::MacroNode] containing information about the macro. Useful for accessing parent and child macros, and the current class[Glyph::Document]. Normally, instances of the code[MacroNode] class contain the following keys: * @:name@, the name of the macro. * @:source@, a @String@ identifying the source of the macro (a file, a snippet, etc.) * @:value@, the value of the macro (populated after the document has been parsed and analyzed). * @:escape@, whether the macro is a =>[#esc_quot|quoting macro] or not. * @:document@, the instance of code[Document] the macro is contained in (populated after the document has been parsed and analyzed). Note that the first two keys can also be accessed via instance variables. ] ] ] tr[ td[code[@name]] td[The name of the macro.] ] tr[ td[code[@source_name]] td[A code[String] identifying the source of the macro (a file, a snippet, etc.).] ] tr[ td[code[@source_topic]] td[A code[String] identifying the source topic of the macro.] ] tr[ td[code[@source_file]] td[A code[String] identifying the source file of the macro.] ] ] ยง[ @title[Representations] txt[ There's a small problem with the code used to define the @note@ macro in the previous section: what if I want to format notes using HTML5 instead of HTML, or another output format? Glyph supports different output formats, therefore macros must be format-independent! In fact, this is the actual source of the @note@ macro: ] highlight[=ruby| macro :note do @data[:name] = @name @data[:text] = value render end =] txt[ The HTML representation of the note macro is defined in the @macros/reps/html.rb@ file as follows: ] highlight[=ruby| rep :note do \|data\| css_class = data[:name].to_s.match(/[a-z0-9_-]/i) ? data[:name] : "note" %{<div class="#{css_class}"> <span class="note-title">#{data[:name].to_s.capitalize}</span>#{data[:text]} </div>} end =] txt[ The HTML5 representation of the note macro, on the other hand, is defined in the @macros/reps/html5.rb@ file as follows: ] highlight[=ruby| rep :note do \|data\| css_class = data[:name].to_s.match(/[a-z0-9_-]/i) ? data[:name] : "note" %{<aside class="#{css_class}"> <span class="note-title">#{data[:name].to_s.capitalize}</span>#{data[:text]} </aside>} end =] Note the different tags used to render the note. ]