add tag
marmot
On this site, but probably also on other topanswers.xyz sites and possibly beyond, codes get shared. If the codes exceed some minimal complexity it may well be that there is a certain usage that allows others to really make use of these codes. That is, one probably should indicate how the code is to be used. Since this is also a LaTeX site, one would think that it should be very straightforward to create such mini documents. Or, so I thought. Well, most likely it is the case, but I actually do not find what I got very convenient. Here is an example which is a quickly written mini-docu to a recent answer.
```
\documentclass[a4paper,fleqn]{ltxdoc}
\usepackage[margin=1in]{geometry}
\usepackage[version=latest]{pgf}
\usepackage{xkeyval,calc,listings,tikz,fp,amsmath,amssymb}
\usepackage[T1]{fontenc}% big thanks to samcarter!
\usepackage{makeidx}
\makeindex
\usepackage{hyperref}
\hypersetup{%
        colorlinks=true,
        linkcolor=blue,
        filecolor=blue,
        urlcolor=blue,
        citecolor=blue,
        pdfborder=0 0 0,
}
\makeatletter          % see https://tex.stackexchange.com/q/33946
\input{pgfmanual.code} % 
\makeatother           % 
\input{pgfmanual-en-macros.tex} % link from
% /usr/local/texlive/2020/texmf-dist/doc/generic/pgf/macros/pgfmanual-en-macros.tex
% or the equivalent on your installation
\def\pgfautoxrefs{1}
%
\usepackage{tikz}
\usepackage[american, siunitx , RPvoltages]{circuitikz}
\usetikzlibrary{arrows.meta,calc}
\tikzset{pics/flow arrow/.style={code={\tikzset{flow arrow pars/.cd,#1}
	\def\pv##1{\pgfkeysvalueof{/tikz/flow arrow pars/##1}}	
	\def\tikzflowarrownone{-}
	\edef\tikzflowarrowfrom{\pv{from}}
	\edef\tikzflowarrowto{\pv{to}}
	\edef\tikzflowarrowfromto{0}
	\ifx\tikzflowarrowfrom\tikzflowarrownone
	 \else
	 \ifx\tikzflowarrowto\tikzflowarrownone
	  \else
	   \edef\tikzflowarrowfromto{1}
	 \fi
	\fi
	\ifcase\tikzflowarrowfromto
	\draw[/tikz/flow arrow pars/arrow,
		to path={(\tikztostart)--(\tikztotarget) \tikztonodes}] 
		(-\pv{l}/2,\pv{d})
		-- node[pos=\pv{pos},above,transform shape,flow arrow pars/edge label]{\pv{t}}
	(\pv{l}/2,\pv{d});
	\or
	  \pgfmathsetmacro{\tikzflowarrowfromfraction}{0.5-\pv{shorten scale}*0.5}
	  \pgfmathsetmacro{\tikzflowarrowtofraction}{0.5+\pv{shorten scale}*0.5}
	  \draw[/tikz/flow arrow pars/arrow,
		  to path={(\tikztostart)--(\tikztotarget) \tikztonodes}] 
  	     ($ ($(\tikzflowarrowfrom)!\tikzflowarrowfromfraction!(\tikzflowarrowto)$)!\pv{d}!90:($(\tikzflowarrowfrom)!\tikzflowarrowtofraction!(\tikzflowarrowto)$) $)
 		  -- 
		  node[pos=\pv{pos},above,transform shape,sloped,flow arrow pars/edge label]{\pv{t}}
          ($ ($(\tikzflowarrowfrom)!\tikzflowarrowtofraction!(\tikzflowarrowto)$)!\pv{d}!-90:($(\tikzflowarrowfrom)!\tikzflowarrowfromfraction!(\tikzflowarrowto)$) $)
	  ;
	\fi
}},flow arrow/.style={to path={
 (\tikztostart) -- pic[sloped,allow upside down]{flow arrow={#1}} (\tikztotarget)}},
 flow arrow pars/.cd,
	l/.initial=2em,d/.initial=1.5ex,arrow/.style={-Latex},
	pos/.initial=0.5,edge label/.style={},
	t/.initial={},t'/.initial={},
	between/.code args={#1 and #2}{\tikzset{flow arrow pars/from=#1,
		flow arrow pars/to=#2}},from/.initial=-,to/.initial=-,
	shorten scale/.initial=0.5
	}
\begin{document}
\section*{Flow arrows}

The |flow arrow| is a |pic| which supports a couple of |keys|.

\begin{key}{/tikz/flow arrow/t=\mvar{node content} (initially empty)}
|t| is the key for the node content (|t| as |text|).
\end{key}
%
\begin{key}{/tikz/flow arrow/edge label=\mvar{style} (initially empty)}
Style that controls the node.
\end{key}
%
\begin{key}{/tikz/flow arrow/arrow=\mvar{style} (initially -Latex)}
|arrow| is the style of the arrow.
\end{key}
%
\begin{key}{/tikz/flow arrow/d=\mvar{length} (initially 1.5ex)}
Distance between decorated line and arrow.
\end{key}
%
\begin{key}{/tikz/flow arrow/l=\mvar{length} (initially 2em)}
Length of the arrow. Only works for arrows that are not constructed with the
|between| or |from| and |to| keys.
\end{key}
%
\begin{key}{/tikz/flow arrow/between=\mvar{coordinate 1} and \mvar{coordinate 2} (initially - and -)}
|between| takes two arguments, e.g.\ |flow arrow={between={Ra.east and La.west}|.
You can alternatively say |from=Ra.east| and |to=La.west|.
\end{key}
%
\begin{key}{/tikz/flow arrow/from=\mvar{coordinate} (initially -)}
Can be used together with |/tikz/flow arrow/to|. Only when both are set the arrow
will be placed parallel to the line from |from| to |to|.
\end{key}
%
\begin{key}{/tikz/flow arrow/to=\mvar{coordinate} (initially -)}
Can be used together with |/tikz/flow arrow/from|. Only when both are set the arrow
will be placed parallel to the line from |from| to |to|.
\end{key}
\begin{key}{/tikz/flow arrow/shorten scale=\mvar{factor} (initially 0.5)}
Determines the length of an arrow that is constructed with the |between| or |from|
and |to| keys. The arrow will have |factor| times the length of the distance between
|from| and |to|. For arrows that are not construncted with the |between| or |from|
and |to| keys the lenght is set by the |/tikz/flow arrow/l| key.
\end{key}

You may placethe |pic| via |pos|.

\begin{codeexample}[width=6cm]
\begin{tikzpicture}
	\draw[semithick] (0,2) to[ R=$R_a$, name=Ra, o-] 
	pic[sloped,pos=1]{flow arrow={t={$I_a$}}}
	++(2,1) 
	to[L,cute inductor, l=$L_a$, name=La, -.]  ++(2,1);
\end{tikzpicture}
\end{codeexample}

Alternatively you may place the |pic| via |between|.
\begin{codeexample}[width=6cm]
\begin{tikzpicture}[baseline=8em]
	\draw[semithick] (0,2) to[ R=$R_a$, name=Ra, o-] 
	++(2,1) 
	to[L,cute inductor, l=$L_a$, name=La, -.]  ++(2,1)
	pic{flow arrow={between={Ra.east and La.west},t={$I_a$},
	edge label/.append style={anchor=center},
	arrow/.append style={shorten >=1em}}};
\end{tikzpicture}
\end{codeexample}
\end{document}
```
![Screen Shot 2020-12-28 at 5.18.08 PM.png](/image?hash=7ffc924ed63978bec75ebb9e791b536a5ae12188819806a4eb36cb6f38bdf674)
The outcome is sort of reasonable but there are many problems.
1. The preamble is excessive. How should a user understand what is needed to make the code work and what is needed to have the manual?
2. I am most likely using commands like `\mvar` incorrectly. Yet there is a reason: I am not aware of a manual in which these things are explained. (So, yes, this is circular. In order to write a manual one needs a manual which explains the ingredients one can use to write a manual...)
3. It is not very convenient either. Because most likely I want to also leave a docu in html. So ideally I would only have to copy the html docu, do minimal editing and get a docu than can be compiled with LaTeX.

On the one hand, I have not seen any machinery that would make life easier here. On the other hand it is hard to imagine that no one has ever thought about this. So the question is whether there are tools that make it easier to document the codes that we are sharing reasonably well.

Enter question or answer id or url (and optionally further answer ids/urls from the same question) from

Separate each id/url with a space. No need to list your own answers; they will be imported automatically.