summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/tex/generic/graphdrawing/lua/pgf/gd/doc.lua
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/pgf/base/tex/generic/graphdrawing/lua/pgf/gd/doc.lua')
-rw-r--r--graphics/pgf/base/tex/generic/graphdrawing/lua/pgf/gd/doc.lua124
1 files changed, 124 insertions, 0 deletions
diff --git a/graphics/pgf/base/tex/generic/graphdrawing/lua/pgf/gd/doc.lua b/graphics/pgf/base/tex/generic/graphdrawing/lua/pgf/gd/doc.lua
new file mode 100644
index 0000000000..78b68bbcb1
--- /dev/null
+++ b/graphics/pgf/base/tex/generic/graphdrawing/lua/pgf/gd/doc.lua
@@ -0,0 +1,124 @@
+-- Copyright 2013 by Till Tantau
+--
+-- This file may be distributed an/or modified
+--
+-- 1. under the LaTeX Project Public License and/or
+-- 2. under the GNU Public License
+--
+-- See the file doc/generic/pgf/licenses/LICENSE for more information
+
+-- @release $Header$
+
+
+---
+-- The table doc is used for documentation purposes. It is used to
+-- provide lazy documentation for keys, that is, to install
+-- documentation for keys only when this information is requested and
+-- when the documentation is kept in a separate file.
+--
+-- Using the doc facility is easy:
+-- %
+-- \begin{enumerate}
+-- \item In the |declare| statement of the key, you do not provide
+-- fields like |documentation| or |summary|. Rather, you provide the
+-- field |documentation_in|, which gets the name of a Lua file the
+-- will be read whenever one of the fields |documentation|, |summary|,
+-- or |examples| is requested for the key.
+-- \item When the key is requested, |require| will be applied to the
+-- filename given in the |documentation_in| field.
+-- \item In this file, you start with the following code:
+-- %
+--\begin{codeexample}[code only]
+--local doc = require 'pgf.gd.doc'
+--local key = doc.key
+--local documentation = doc.documentation
+--local summary = doc.summary
+--local example = doc.example
+--\end{codeexample}
+-- %
+-- This will setup nice shortcuts for the commands you are going to
+-- use in your file.
+-- \item Next, for each to-be-lazily-documented key, add a block to
+-- the file like the following:
+-- %
+--\begin{codeexample}[code only]
+-- ---
+-- key "my radius"
+-- summary "This key specifies a radius."
+-- documentation
+-- [[
+-- This key is used, whenever...
+-- ]]
+-- example "\tikz \graph [foo layout, my radius=5] { a--b };"
+-- example "\tikz \graph [foo layout, my radius=3] { c--d };"
+--\end{codeexample}
+--
+-- Note that |[[| and |]]| are used in Lua for raw multi-line strings.
+--
+-- The effect of the above code will be that for the key |my radius|
+-- the different field like |summary| or |documentation| get
+-- updated. The |key| function simple ``selects'' a key and subsequent
+-- commands like |summary| will update this key until a different key
+-- is selected through another use of |key|.
+-- \end{enumerate}
+
+local doc = {}
+
+local current_key
+
+
+-- Namespace
+require "pgf.gd".doc = doc
+
+
+-- Imports
+local keys = require "pgf.gd.interface.InterfaceCore".keys
+
+---
+-- Selects the key which will be subsequently updated by the other
+-- functions of this class.
+--
+-- @param key A key.
+
+function doc.key (key)
+ current_key = assert(keys[key], "trying to document not-yet-declared key")
+end
+
+
+---
+-- Updates (replaces) the summary field of the last key selected
+-- through the |key| command.
+--
+-- @param string A (new) summary string.
+
+function doc.summary (string)
+ current_key.summary = string
+end
+
+
+---
+-- Updates (replaces) the documentation field of the last key selected
+-- through the |key| command.
+--
+-- @param string A (new) documentation string. Typically, the |[[|
+-- syntax will be used to specify this string.
+
+function doc.documentation (string)
+ current_key.documentation = string
+end
+
+
+---
+-- Adds an example to the |examples| field of the last key selected
+-- through the |key| command.
+--
+-- @param string An additional example string.
+
+function doc.example (string)
+ local examples = rawget(current_key, "examples") or {}
+ examples[#examples + 1] = string
+ current_key.examples = examples
+end
+
+
+return doc