0

I have a few packages that provide some TikZ based pics.

Originally I've written these using the dtxdoc class file but have started switching over to l3doc files. When I use the newmacro environments to comment upon a pic I'm now getting messages that the macro is not defined in the package documentation. The reason for the message is that dtxdoc didn't care whether you defined the macro or not while l3doc does. Practically this is spot on since I'm defining keys in the pgfkey system and not macros.

So I had a scrounge around in the TikZ documentation and found the key environment is usually used to document TikZ/PGF keys just it does not seem to be a part of any package that the pre-amble imports. Has anyone used this or seen a doc for this ?

There is a comment or two on using the codeexample environment in dtxdoc's on this site but I haven't found any references to the key environment.

% \iffalse meta-comment
%
% Copyright (C) 2016 by Carel <carel@texexchange.com>
% ---------------------------------------------------------
%
% This file may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either
% version 1.2 of this license or (at your option) any later
% version. The latest version of this license is in:
%
% http://www.latex-project.org/lppl.txt
%
% and version 1.2 or later is part of all distributions 
% of LaTeX version 1999/12/01 or later.
%
% \fi
% \iffalse
%
% ^^A Identification
%
%<*driver>
\ProvidesFile{tikzkit.dtx}
%</driver>
%
% ^^A Package Provides
%
%<Pkg>\NeedsTeXFormat{LaTeX2e}[1994/06/01] % 1994/06/01 - First revision of the  LaTeX kernel to support error handling
%<Sty>\ProvidesPackage{tikzkit}
%<*Sty>
[2016/09/15 v0.1 TikZkiT provides complimentary code for TikZ]
%</Sty>
%
% ^^A Package Requires
%
%^^A <STY>\RequirePackage{PACKAGE} % Substitute any required packages
%^^A<Sty>\RequirePackage{menukeys}
%
% ^^A Package Installation
%
%<*batchfile>
\begingroup
%%
%% Copyright (C) 2016 by Carel
%%
%% This file may be distributed and/or modified under the
%% conditions of the LaTeX Project Public License, either
%% version 1.2 of this license or (at your option) any later
%% version. The latest version of this license is in:
%%
%% http://www.latex-project.org/lppl.txt
%%
%% and version 1.2 or later is part of all distributions of
%% LaTeX version 1999/12/01 or later.
%%

\input docstrip.tex
\keepsilent

\usedir{tex/latex/TikZkiT}

\preamble

This is a generated file.

Copyright (C) 2016 by Carel

This file may be distributed and/or modified under the
conditions of the LaTeX Project Public License, either
version 1.2 of this license or (at your option) any later
version. The latest version of this license is in:

  http://www.latex-project.org/lppl.txt

and version 1.2 or later is part of all distributions of
LaTeX version 1999/12/01 or later.

\endpreamble

\askforoverwritefalse         % ^^A Always overwrite
%^^A \IfFileExists{<>}{}{...} % ^^A Protect if exists
\generate{\file{TikZkiT/tikzkit.sty}{\from{TikZkiT.dtx}{Pkg,Sty}}}
\generate{\file{TikZkiT/pgflibraryTikZkiT.code.tex}{\from{TikZkiT.dtx}{Pkg,Pgf}}}
\generate{\file{TikZkiT/tikzlibraryTikZkiT.code.tex}{\from{TikZkiT.dtx}{Pkg,TikZ}}}
\generate{\file{TikZkiT/pgflibraryshapes.TikZkiT.code.tex}{\from{TikZkiT.dtx}{Pkg,Pics}}}

\endgroup
%</batchfile>
%
% ^^A Documentation Generation
%
%<*driver>
\documentclass{l3doc}
 \usepackage{tikzkit}
 \usepackage[version=latest]{pgf}
 \usepackage{tikz}
 \usepackage{xkeyval,calc,listings,fp}
 \usepackage{menukeys}
 \usetikzlibrary{TikZkiT}
 \newmenumacro{\TeXPath}[/]{hyphenatepathswithfolder}
 \newmenumacro{\TeXFile}[/]{hyphenatepaths}
 \EnableCrossrefs
 \CodelineIndex
 \RecordChanges
%^^A \OnlyDescription % User optionally sets this with \AtBeginDocument{} in ltxdoc.cfg do not enforce.
\begin{document}
 \DocInput{tikzkit.dtx}
 \PrintChanges
 \PrintIndex
\end{document}
%</driver>
% \fi
%
% ^^A Boiler Plate
%
% \CheckSum{0} % ^^A Set the number of backslash characters in the document
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
% ^^A Change log
%
% \changes{v0.0}{2016/09/15}{Initial version}
%
% ^^A Package version information
%
% \GetFileInfo{TikZkiT.dtx}
%
% ^^A Common Commands
%
% \DoNotIndex{\newcommand,\newenvironment,\newcounter,\def,\edef}   
% \DoNotIndex{\#,\$,\%,\&,\@,\\,\{,\},\^,\_,\~,\ }
% \DoNotIndex{\@ne}
% \DoNotIndex{\begingroup,\endgroup,\closein,\closeout,\advance,\catcode}
% \DoNotIndex{\if,\else,\fi,\empty}
% \DoNotIndex{\day}
% \DoNotIndex{\arabic}
% \DoNotIndex{\tiny,\small,\large}
% \DoNotIndex{\circ}
% \DoNotIndex{\jobname}
% \DoNotIndex{\tikzset}
%
% ^^A Attribution and Title
%
% \title{The \textsf{TikZkiT} package\thanks{This document
% corresponds to \textsf{TikZkiT}~\fileversion,
% dated~\filedate.}}
% \author{Carel \\ \texttt{carel@texexchange.com}}
%
% \maketitle
%
% ^^A Package Abstract
%
% \begin{abstract}
% This package provides various PGF/TikZ features
% \end{abstract}
%
% ^^A Introduction
%
% \section{Introduction}
%
% This package provides a few keys that I have need for on occasion.
% It is an attempt at gathering these keys, scattered in ones pre-ambles, into a single package.
%
% ^^A Installation
%
% \section{Installation}
%
% The following table lists the final installation locations files provided by this package.
%
% \begin{tabbing}
% \hspace{1em}\=\hspace{1em}\=\hspace{1em}\=\hspace{17em}\=\\\kill
% \TeXPath{\TeX MF}                                                \>\>\>\> \TeX\ system's root folder          \+\\
% \TeXPath{tex/generic/pgf}                                          \>\>\> PGF/TikZ root folder                \+\\
% \TeXPath{frontendlayer/tikz/libraries}                               \>\> TikZ layer's libraries              \+\\
% \TeXFile{tikzlibraryTikZkiT.code}                                      \> TikZkiT library                     \-\\
% \TeXPath{libraries}                                                  \>\> PGF layer's libraries               \+\\
% \TeXFile{pgflibraryTikZkiT.code}                                       \> TikZkiT library                     \-\\
% \TeXPath{libraries/shapes}                                           \>\> shape libraries                     \+\\
% \TeXFile{pgflibraryshapes.TikZkiT.code}                                \> TikZkiT shapes                        \\
% \end{tabbing}
%
% ^^A Usage
%
% \section{Usage}
%
% This is still under development
%
% ^^A Macro Description
%
%^^A \DescribeMacro{\<MACRO>}
%^^A A paragraph describing a |\<MACRO>| it options, arguments and usage.
%^^A An reference to the macro may be placed in the index using \index{<DESCRIPTION>|<CATEGORY>}
%
%^^A \DescribeEnv{<ENVIRONMENT>}
%^^A A paragragrph describing an |<ENVIRONMENT>|, it's options, arguments and usage.
%
% \StopEventually{\PrintChanges \PrintIndex} ^^A Text between here and \Finally is not shown if \OnlyDescription is used.
%
% ^^A Implementation
%
% \section{Implementation}
%
% ^^A Package Implementation
%
% The PGF manual documents the package structure in the section entitled ``The Hierarchial Structure of the package''.
%
% \subsection{TikZ Layer}
%
%\iffalse
%<*TikZ>
%\fi
%
% Initially a name space/scope is setup to accomodate the TikZkiT code.
%
%^^A\begin{key}{/tikz/TikZkiT=\meta{TikZkiT}}
%    \begin{macrocode}
\tikzset{
  TikZkiT/.is family,
}
%    \end{macrocode}
%^^A\end{key}
%
% Although the main purpose of the front end code is to load the appropriate PGF libraries.
%
%    \begin{macrocode}
\usepgflibrary{TikZkiT}
%    \end{macrocode}
%
%\iffalse
%</TikZ>
%\fi
%
% \subsection{PGF Layer}
%
%\iffalse
%<*Pgf>
%\fi
%
% The library file defines any defaults required for the component libraries it imports.
%
%    \begin{macrocode}
\usepgflibrary{shapes.TikZkiT}
%    \end{macrocode}
%
%\iffalse
%</Pgf>
%\fi
%
% \subsection{Shapes Library}
%
%\iffalse
%<*Pics>
%\fi
%
% \begin{macro}{\b@sis} \changes{v0.0}{2016/09/15}{Included a common base length for diagrams}
% \begin{macro}{\basis} \changes{v0.0}{2016/09/15}{Included macro for accessing the base length}
%    \begin{macrocode}
\newlength{\b@sis}
%    \end{macrocode}
% This length is now accessible within user defined macros but we also need to make it available to TikZ.
%    \begin{macrocode}
\tikzset{
  TikZkiT,
  basis/.store in=\b@sis,
  basis/.default={1 em},
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
%\iffalse
%</Pics>
%\fi
%
% ^^A Macro Templates
%
%^^A % \begin{macro}{\<MACRO>}
%^^A % Describe the macro |\<MACRO>| and it's \marg{mandatory}, \oarg{optional} and \parg{picture} arguments along with any \meta{other} information.
%^^A % \changes{v<MAJOR>.<MINOR>}{<YEAR>/<MONTH>/<DATE>}{<MESSAGE>}
%^^A %    \begin{macrocode}
%^^A \newcommand{\<MACRO>}[]{}
%^^A %    \end{macrocode}
%^^A % \end{macro}
%
%^^A % \begin{environment}{<ENVIRONMENT>}
%^^A % Describe the environment |<ENVIRONMENT>| and it's implementation here.
%^^A % \changes{v<MAJOR>.<MINOR>}{<YEAR>/<MONTH>/<DATE>}{<MESSAGE>}
%^^A % \begin{macrocode}
%^^A \newenvironment{<ENVIRONMENT>}{}{}
%^^A % \end{macrocode}
%^^A % \end{environment}
%
% ^^A Prompt
%
% \Finale
%\typeout{***********************************************************}
%\typeout{*                                                         *}
%\typeout{* To finish the installation you have to move the         *}
%\typeout{* following file into a directory searched by TeX:        *}
%\typeout{*                                                         *}
%\typeout{* \space\space TikZkiT.sty                                *}
%\typeout{*                                                         *}
%\typeout{* To produce the documentation run the file TikZkiT.dtx   *}
%\typeout{* through LaTeX.                                          *}
%\typeout{*                                                         *}
%\typeout{* To product the correct index and glossary you may also  *}
%\typeout{* have to run the following two commands                  *}
%\typeout{*                                                         *}
%\typeout{* makeindex -s gglo.ist -o TikZkiT.gls TikZkiT.glo        *}
%\typeout{* makeindex -s gind.ist -o TikZkiT.ind TikZkiT.idx        *}
%\typeout{*                                                         *}
%\typeout{* Happy TeXing!                                           *}
%\typeout{***********************************************************}
\endinput
  • Can you please provide a minimal example? – cfr Sep 16 '16 at 0:08
  • @cfr I've included a dtx that will compile and shows the little error message about not having defined the macro. Originally I didn't think that any code was necessary as it's more a question about where to find a doc or a reference to the key environment. – Carel Sep 16 '16 at 14:40
  • @cfr I found the source file for this environment so it's sorted for now. Thanks – Carel Sep 16 '16 at 15:39
1

After a bit more scrounging around I found a file called pgfmanual-en-macros.tex which provides the key environment used in the TikZ/PGF manual. I made a copy of this and placed it into the root folder where I compile my packages. I input this file into the packages' pre-amble and it seems to all work. If you want the updated code just leave a comment for me to post it and I shall do so.

Legally, I understand I'm allowed to do so as the file is prefixed with a message stating that it may be used under either LPPL or GPL licensing.

  • I wonder if there is any reason this is not available as say a TikZdoc package. There was mention somewhere that the macros for the pgfmanual had been split off from the manual itself and that some one was trying to package it, I don't know what came of that and can't seem to find it again. – Carel Sep 16 '16 at 15:40

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.