summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc.lua
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2014-02-27 00:01:50 +0000
committerKarl Berry <karl@freefriends.org>2014-02-27 00:01:50 +0000
commit90ae413a94da014dbf7a6a8ab584f7c668483a5a (patch)
tree4e0528a2b2fb2004988e7fc804ea2f1354f1f5d5 /Master/texmf-dist/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc.lua
parent800cc56380d1edfe567a6a66bef13e8950eb2b0c (diff)
pgf 3.0.0
git-svn-id: svn://tug.org/texlive/trunk@33057 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc.lua')
-rw-r--r--Master/texmf-dist/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc.lua122
1 files changed, 122 insertions, 0 deletions
diff --git a/Master/texmf-dist/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc.lua b/Master/texmf-dist/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc.lua
new file mode 100644
index 00000000000..5d02603943c
--- /dev/null
+++ b/Master/texmf-dist/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc.lua
@@ -0,0 +1,122 @@
+-- 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: /cvsroot/pgf/pgf/generic/pgf/graphdrawing/lua/pgf/gd/doc.lua,v 1.2 2013/03/20 17:16:38 tantau Exp $
+
+
+---
+-- 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