Difference between revisions of "CLD"

From Wiki
Jump to navigation Jump to search
(Links to cld-mkiv.pdf; tiny example illustrating syntactical peculiarities of clds.)
 
 
(14 intermediate revisions by 6 users not shown)
Line 1: Line 1:
CLD (''ConTeXt Lua Documents'') are way to access TeX from inside Lua scripts; they provide means to typeset documents using little to no TeX code at all.
+
'''ConTeXt Lua Documents''' (CLD) are way to access TeX from inside Lua scripts; they provide means to typeset documents using little to no TeX code at all.
 
This makes them especially helpful for automated content generation and scripting.
 
This makes them especially helpful for automated content generation and scripting.
 
Internally, the Lua commands are mapped onto their ConTeXt and TeX counterparts.
 
Internally, the Lua commands are mapped onto their ConTeXt and TeX counterparts.
Line 5: Line 5:
 
If you ever dreamed of proper typesetting without backslashes galore, here is where to start at.
 
If you ever dreamed of proper typesetting without backslashes galore, here is where to start at.
  
== Basic reading ==
+
= Basic reading =
* [www.pragma-ade.com/general/manuals/cld-mkiv.pdf The CLD manual] by Hans Hagen.
+
* [http://www.pragma-ade.nl/general/manuals/cld-mkiv.pdf The CLD manual] by Hans Hagen.
* [[source:mult-cld.lua| The source code.]]
+
* {{src|cldf-ini.lua}}: the entry point for the '''cldf-*''' files that contain the CLD implementation.
  
== An Example ==
+
= An Example =
 
Writing CLDs is straightforward although there are some pitfalls.
 
Writing CLDs is straightforward although there are some pitfalls.
 
Suppose we want to typeset the following minimal example:
 
Suppose we want to typeset the following minimal example:
Line 33: Line 33:
 
</context>
 
</context>
  
With CLDs this will require more verbosity because nesting -- in the present example a <code>framed</code> inside a <code>placefigure</code> -- has to be expressed through functions.
+
As <em>CLD</em> this will require more verbosity because nesting -- in the present example a <code>framed</code> inside a <code>placefigure</code> -- has to be expressed through functions.
 
Optional and key-value style arguments are expressed as arrays and dictionaries respectively, which is a transparent representation of their ConTeXt ancestors.
 
Optional and key-value style arguments are expressed as arrays and dictionaries respectively, which is a transparent representation of their ConTeXt ancestors.
 
Mandatory (grouped) arguments are given either as strings or as functions.
 
Mandatory (grouped) arguments are given either as strings or as functions.
  
The following example shows two ways of rewriting the above TeX code: the first one closely resembles its structure while the second calls the function <code>test</code> from inside the <code>placefigure</code> macro -- NB: it is compulsory to call a declared function from by means of another function, otherwise ConTeXt can't process it.
+
== Nesting 1: Functions ==
(Works with latest ConTeXt beta as of 2010-03-10.)
+
The following example shows two ways of rewriting the above TeX code: the first one closely resembles its structure while the second calls the function <code>test</code> from inside the <code>placefigure</code> macro.
 +
 
 
<pre>
 
<pre>
 
context.placefigure(
 
context.placefigure(
Line 69: Line 70:
  
 
</pre>
 
</pre>
 +
 +
== Nesting 2: Delayed ==
 +
 +
An alternative to the function encapsulation is provided by
 +
the <tt>context.delayed.f()</tt> method.
 +
This way execution of the <tt>\input</tt>
 +
command is prevented until <tt>\placefigure</tt> is passed to TeX,
 +
the obvious advantage being that the source code follows the
 +
original TeX code and that it eliminates the need to create
 +
a separate function.
 +
 +
<pre>
 +
context.placefigure(
 +
    "none",
 +
    function()
 +
        context.framed( {
 +
            frame="on",
 +
            align="middle"
 +
        }, 
 +
            context.delayed.input("knuth")
 +
        )
 +
    end
 +
)
 +
</pre>
 +
 +
= Setting up Header Texts =
 +
 +
As already shown in the section about Nesting 1: Functions also context.setupheadertexts needs to be called with functions. On top of this we need to know, that once context.setupheadertexts is executed it is not frozen. This makes it necessary, that we need to add "return true" inside each used function() call. This makes sure that the called function stays around until the run is finished.
 +
 +
A complete setup of header texts in a double-sided ConTeXt Lua Document could look then like this
 +
 +
<pre>
 +
context.setupheadertexts(
 +
  {function()
 +
    context.getmarking({"chapter"})
 +
    return true
 +
  end
 +
  },
 +
  {function()
 +
    context.pagenumber()
 +
    return true
 +
  end
 +
  },
 +
  {function()
 +
    context.getmarking({"section"})
 +
    return true
 +
  end
 +
  },
 +
  {function()
 +
    context.pagenumber()
 +
    return true
 +
  end
 +
  })
 +
</pre>
 +
 +
 +
[[Category:Programming and Databases]]

Latest revision as of 18:47, 25 August 2022

ConTeXt Lua Documents (CLD) are way to access TeX from inside Lua scripts; they provide means to typeset documents using little to no TeX code at all. This makes them especially helpful for automated content generation and scripting. Internally, the Lua commands are mapped onto their ConTeXt and TeX counterparts. Knowledge of the latter is, therefore, a prerequisite to writing CLDs. If you ever dreamed of proper typesetting without backslashes galore, here is where to start at.

Basic reading

An Example

Writing CLDs is straightforward although there are some pitfalls. Suppose we want to typeset the following minimal example:

\starttext
\placefigure {none} {%                                                                                                     
  \framed [frame=on, align=middle] {%
    \input knuth
  }%
}%
\stoptext

As CLD this will require more verbosity because nesting -- in the present example a framed inside a placefigure -- has to be expressed through functions. Optional and key-value style arguments are expressed as arrays and dictionaries respectively, which is a transparent representation of their ConTeXt ancestors. Mandatory (grouped) arguments are given either as strings or as functions.

Nesting 1: Functions

The following example shows two ways of rewriting the above TeX code: the first one closely resembles its structure while the second calls the function test from inside the placefigure macro.

context.placefigure(
    "none",
    function()
        context.framed( {
            frame="on",
            align="middle"
        },  
            function() context.input("knuth") end 
        )   
    end 
)

context.par()

function text ()
    context.framed( {
            frame="on",
            align="middle"
        },  
        function() context.input("knuth") end 
    )   
end

context.placefigure(
    "none",
    function () text() end                                                                                                 
)

Nesting 2: Delayed

An alternative to the function encapsulation is provided by the context.delayed.f() method. This way execution of the \input command is prevented until \placefigure is passed to TeX, the obvious advantage being that the source code follows the original TeX code and that it eliminates the need to create a separate function.

context.placefigure(
    "none",
    function()
        context.framed( {
            frame="on",
            align="middle"
        },  
            context.delayed.input("knuth")
        )
    end 
)

Setting up Header Texts

As already shown in the section about Nesting 1: Functions also context.setupheadertexts needs to be called with functions. On top of this we need to know, that once context.setupheadertexts is executed it is not frozen. This makes it necessary, that we need to add "return true" inside each used function() call. This makes sure that the called function stays around until the run is finished.

A complete setup of header texts in a double-sided ConTeXt Lua Document could look then like this

context.setupheadertexts(
  {function()
     context.getmarking({"chapter"})
     return true
   end
  },
  {function()
     context.pagenumber()
     return true
   end
  },
  {function()
     context.getmarking({"section"})
     return true
   end
  },
  {function()
     context.pagenumber()
     return true
   end
  })