Efficient ways of generating mini documentations - TeX

TopAnswers TeX

Meta

Databases

TeX

Code Golf

APL

C++

.net

db<>fiddle

Java

*nix

PHP

PowerShell

Python

Rust

टेक्-मराठी

Typst

Web Client Dev

Web Server Dev

Efficient ways of generating mini documentations

add tag

user 3.14159

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.

Please, create an exemplary concept question and a follow-up on it to make everyone know how things work. You can make both posts public with a keyword in the titles implying that the post is a tutorial not a real one.

Perhaps it would possible to have a little Wiki for that so that more people have access to the information? I am probably not a really good target for a sandbox because (a) it is hibernation season and (b) I need to get more familiar with all the terms like "markdown", which I could by learning from other people's examples. :smile_cat:

the system is flexible enough that you may be able to adapt it for tex.ta — for example the words 'concept', 'warning', 'example' aren't fixed and can be set to anything you want (on php.ta a similar post type is called 'documentation')

The idea of a 'concept' post is that it would then be linked to in normal answers so that the concept itself doesn't need to be repeated — and the answer can then just contain the "thoughts/applications" that @Diaa mentions.

@marmot, re: [your question](#question), have you seen the 'concept' type Q&A on some other TA communitiees? e.g. this one on dba.ta: https://topanswers.xyz/databases?q=1092. I wonder if there is some cross-over with your thinking here though obviously you are asking about tools in particular.

In my comment I wanted to say that the tex.se site does not seem to work as one could have hoped. Naively one would think that if a very similar question came up already, users seeking information could just get what they want from older threads. However, this does not seem to happen. Rather, they ask questions that can be answered with posts that already exist. (Of course, there is certainly a number of users who do precisely that, and do not end up asking a question, but the fact that still so many repetitive questions get asked just means that this is not working for everyone.) Now, the last thing the owners/maintainers of tex.se and the other commercial Q & A sites want is that almost all problems get solved through their database. If that was the case, they would not make money with advertisement etc. So they create this perpetual machinery in which users get rewarded for copying an existing post and selling it as their own. On the other hand, I am wondering if there is a way how one could make this scheme more sustainable. Certainly others must have thought about this before. And as for the manuals, I think that there is a need for different type of manuals. Some short ones which are just a reference to look up things, and some with tutorials and complete code examples from which one could learn. The latter ones can be supplemented in Q & A sites, where the package authors or others can give examples. But all of this only works if things get properly cross referenced.

If you don't want me to ask a repetitive question, then you should make the information I am looking for available in the package manual. Yet, that won't stop many (including me :D) from asking the same question since they are looking for a discussion about their thoughts/applications as well. Also, making documentation out of previous Q/As is not an easy job since who is responsible for it? and why should anyone spend time making that unless he/she does it for passion or as a part of his/her job? So, IMHO, the most practical way is to go with enhancing the packages manuals or creating a parallel one of "examples of usage".

Yes, maybe. Yet it also may be that the current version of Q & A sites is not really sustainable. What I want to say is that the questions on tex.se are *very* repetitive. Even worse, any not-so-easy-to-answer question will be ignored or remain unanswered for a long time whereas the duplicates are spotted by senior users, who have nothing better to do than to post a slight modification of an existing answer by another user under their name without attribution. So this game keeps repeating and repeating, and the search engines bring you to a not-so-useful answer which is why slight modifications of the same questions keep dominating tex.se. This might mean that a better conceptual design may allow the users to find more accessible information. And in my humble opinion, while TopAnswers does have some advanced features such as code formatting in comments, there might be ways to make the information even more accessible. One way could be little snippets that illustrate the usage, but this only works if creating these snippets is not too much efforts.

Actually, as you know, QAs sites are not intended for afterlife documentation They are just a drive through exchange piece of information. So, we have to deal with it by a forcible manual integration with another more documentation-oriented site.

Thanks! Yes, i am aware of GitHub, I have some posts there such as [this one](https://github.com/marmotghost/tikz-3dtools). But this does not really blend into this site, does it? Of course, one can definitely move more complicated codes to GitHub. But what about some rather simple codes? It is sort of ironic that on this TeX site the descriptions of the codes have such a limited access to styling and layout.

@marmot, re: [your question](#question), I am happy to find my question featured here :D. For your question, your codes should be integrated in the packages manuals in the examples of usage section. Otherwise, you need to go with texample.net or github.com (which I prefer) due to the ability of tracking the codes versions and issuing support/bugs tickets.

Yes, this could well be. It is very possible that there are already solutions out there somewhere. The example I posted has many drawbacks, but I could totally imagine that there are some who have created something that works. It could well be that the code examples need to be `standalone` documents and so on.

I keep thinking of the link I sent you last time (the repository @ Columbia with a latex back end). The nice feature there is the flagging of files. Could not it solve your question about the html and latex version of your minimal standardized example? Your answer would have the great virtue of either mentioning previous code, or contribute to a new one, and you get an example linked to it. Each answer is always adding a piece to the cathedral.

Oh I get what you mean. I remember one user whose only target was giving answers from others. Without reference of course. I think it could be some people are (relative) stars (lol) due to a chocolate vote system.

First of all, I have learned over the years, and am still learning, so the style of the answers changed, and continues to change. The only thing I tried to do more or less from the start was to add links to earlier answers I was building on. And no, I have not organized the files, I think many of the answers are simply lost. Yet I should say that this isn't really a big loss, I am mainly fooling around. But I do think that better documentation might be a way of avoiding repetition. (This may be more efficient than just calling users names for asking about something that others already understand. How on earth can users avoid asking simple questions if all the high reputation users avoid giving credit to earlier answers, and thus avoid links, just to impress others?)

@marmot, re: [your question](#question), I presume among your 2^100 answers over the years, you reused part of your codes in other answers. Hence my question. How can you flag the snippets/tricks/explanation you're likely to reuse as part of a new answer? As such, you'd have created an organized database of your codes (more personal... How have you managed all these answers in terms of file organization over the years? 💪)

0 Answers