How to document class/package options using `documentation` lib?

[muzimuzhi]

It seems this issue was cleverly sidestepped in tcolorbox manual, probably because each of its package options has a corresponding key /tcb/library/<pkg option> defined which can be used as \tcbuselibrary{<pkg option>, <pkg option>, ...}.

csvsimple.pdf documents its two package options alongside with the introduction to csvsimple-l3 and csvsimple-lagency packages.

I also found that the names \colOpt{<text>}, /tcb/color option=<color>, and color Option which may be considered suitable for options, are already taken by optional texts.

[T-F-S]

Is your own proposal https://github.com/T-F-S/tcolorbox/issues/259 a possible answer? With removing the root \, package options could be documented just like keys without path. Even your /tcb/doclang/key trick may be used to add something like package option, if that may be required.

[muzimuzhi]

Is your own proposal #259 a possible answer?

Sure it is. But as I said in #259, from the partial key name doclang, I felt setting dynamic values to /tcb/docloang/xxx keys is more like a misuse.

[T-F-S]

Sure it is. But as I said in #259, from the partial key name doclang, I felt setting dynamic values to /tcb/docloang/xxx keys is more like a misuse.

Yes, the naming is not inviting for the purpose. When I'm going to see for https://github.com/T-F-S/tcolorbox/issues/259, I try to keep that in mind and provide a solution.

[muzimuzhi]

Another aspect. documentation library provides two kinds of interfaces:

• long version which provides envs and an aux command, for example docCommand(*), docCommands, and \docAuxCommand for commands
• short version which provides only a single command, like \docLength and \docColor.

If the decision is to provide a short version \docOption for package options, then my proposal(s) in #259 won't help.

[T-F-S]

I see package options, well, as options like keys. With https://github.com/T-F-S/tcolorbox/issues/259 implemented, one can distinguish between package options and 'normal' keys, if required:

\documentclass{article}
\usepackage{tcolorbox}
\tcbuselibrary{documentation}
\hypersetup{colorlinks}

\makeindex

%\newcommand{\myFormatDocOption}[1]{#1 (package option)}
%\newcommand{\myFormatDocOptions}[1]{#1 (package options)}

\newcommand{\myFormatDocOption}[1]{package option}
\newcommand{\myFormatDocOptions}[1]{Package options}

\tcbmakedocSubKey[
    doc key prefix=,
    index key formatter=\myFormatDocOption,
    index keys formatter=\myFormatDocOptions
]{docDocOption}{}

\begin{document}

\begin{docDocOption}{a4paper}{}{}
  content
\end{docDocOption}

\printindex
\end{document}

The commented version of \myFormatDocOption(s) contains 'key' or 'Keys' while the not commented overwrites the language settings.

[muzimuzhi]

Just one limitation: if index colorize is set to true, then indices for options and keys will always in color /tcb/doc key. More precisely, the value of \kvtcb@col@key at the time \printindex is used.

Writing value of \kvtcb@col@key to .idx will introduce limitation on the color (expression) passed to /tcb/doc key, as characters commonly used in color expressions like ! have special meaning in \index{<index entry>}.

[muzimuzhi]

Typo: /tcb/doc key mentioned in my previous comment should all be /tcb/color key.

[T-F-S]

From my point of view, this is sufficiently solved by https://github.com/T-F-S/tcolorbox/issues/259