1

Background

I have seen beautiful manuals with commands and descriptions of what they do. I have a shared preamble (edited by multiple people and used for multiple documents) that has a multitude of custom commands created with

  • \newcommand
  • \DeclareRobustCommand
  • \DeclareDocumentCommand (xparse package)
  • \renewcommand
  • etc.

and a multitude of environments

  • \newenvironment
  • \NewEnviron (environ package)
  • etc.

Recently, I asked the question: Is there a way to iterate over all defined colors without mentioning them again?

It turned out to be great! I was wondering whether I can do something similar with commands and their environments despite all of their complexities. All of my commands and environments have a three letter prefix, e.g. mbm (for "made by me").

Goal

I would use this to create a template list of left-aligned commands/environments, followed by an aesthetically-pleasing space followed by a description of that command or environment.

Example with Pseudocode

\documentclass{article}
\usepackage{fontspec}
\usepackage{listings}
\usepackage{tikz}
\usepackage{pgffor}

% Commands
\newcommand\mbmA{elephants}
\newcommand\mbmB[1]{#1}
\newif\ifcolormodules
\DeclareRobustCommand{\mbmmodule}[1]{%
\textbf{\textit{{\ifcolormodules\color{green}\fi #1}}}%
}%
\newcommand{\dq}[1]{\char"201C{}#1\char"201D{}} % Exception to mbm prefix rule
\newcommand{\sq}[1]{\char"2018{}#1\char"2019{}} % Exception to mbm prefix rule
% Environments
\lstnewenvironment{mbmlstcode}{\lstset{basicstyle=\ttfamily\small,columns=fullflexible,keepspaces=true,basewidth=0.5em}}{}
\NewEnviron{mbmerrors}{%
\BODY
}


\begin{document}


\section{Commands}
\foreach \definedcommand in {defined commands} % pseudo-code
\begin{tikzpicture}
   \node [minimum width=3cm, minimum height=1cm,text=red] {\string\definedcommand}; % pseudo-code
\end{tikzpicture}


\section{Environments}
\foreach \definedenvironment in {defined environment} % pseudo-code
\begin{tikzpicture}
   \node [minimum width=3cm, minimum height=1cm,text=orange] {\string\definedenvironment}; % pseudo-code
\end{tikzpicture}


\end{document}
Community
  • 1
Jonathan Komar
  • 13,297
  • 2
    may be help http://tex.stackexchange.com/questions/222861/automatically-clean-numerous-customization-macros-gathered-in-an-auxiliary-fil – touhami Apr 10 '15 at 07:36
  • 1
    It seems definitely possible to use this approach to do what he whishes, but I guess if you want to create a documentation of this piece of code, it would be better suited to make use of the package documentation tools already existing. You might want to have a look at the CTAN list of documentation creation packages or more specifically the dox package. – Samuel Albert Apr 10 '15 at 08:39
  • @Jonathan Komar I just come upon a similar problem working on a larger document with several people. Different commands for basically the same thing were defined and mixed up. It would have been very convinient to have such a list of commands automatically provided to every author. Did you find a proper solution for this question by now? If so, would you mind sharing this solution as answer to your own question? – Dave Jan 25 '19 at 12:35
  • 1
    @Dave, I ended up just using grep and searching for patterns. The only way to do that would be to redefine each command to include a writeout to some list that could be printed later. It was not worth the effort...for color definitions, however, I did create such a command where I defined groups of colors called palettes (accent colors, main colors) whose list I could easily print. – Jonathan Komar Jan 25 '19 at 13:32
  • @JonathanKomar What is about defining something like \documentednewcommand{\command}{<Documentation for \command>} and similar commands for environments etc. and let these write in the aux-file such that you can print a list of commands just like a list of figures in the end? That is how I would have approached it. Or is there an inherent problem with this approach? – Dave Jan 25 '19 at 13:43
  • 1
    @Dave That approach would work but has issues. The foremost reason is one of sheer complexity: not every def is alike (but finite set, so possible). You have the preexpanded ones and non-expanded (def/edef). You have protected ones too. The viability of your approach depends on how much time you are willing to spend. I determined it was not worth my time. Learn C or something, it would be easier ;) Anyway, I will post an answer of my half-solution. – Jonathan Komar Jan 26 '19 at 07:08
  • @JonathanKomar Thank you for sharing your approach :-) I see the problem with the many different ways of defining a command. However, about 80%-90% of the commands I define are just \newcommand{.... For the reamining 10%-20%, I could imagine to have a command that allows to add an additional documentation entry manually. – Dave Jan 26 '19 at 11:10
  • @Dave This is what I ended up doing: https://tex.stackexchange.com/questions/240317/how-can-i-typeset-an-environment-and-its-literal-equivalent-in-an-environment – Jonathan Komar Feb 07 '19 at 14:34

0 Answers0