%D \module
%D   [       file=strc-des,
%D        version=2008.10.20,
%D          title=\CONTEXT\ Structure Macros,
%D       subtitle=Descriptions,
%D         author=Hans Hagen,
%D           date=\currentdate,
%D      copyright={PRAGMA ADE \& \CONTEXT\ Development Team}]
%C
%C This module is part of the \CONTEXT\ macro||package and is
%C therefore copyrighted by \PRAGMA. See mreadme.pdf for
%C details.

\writestatus{loading}{ConTeXt Structure Macros / Descriptions}

\unprotect

\installcorenamespace{description}

\installcommandhandler \??description {description} \??description

\aliased\let\setupdescriptions\setupdescription

% \setupdescription % check with old
%   [\c!alternative=\descriptionparameter\c!location,
%    \c!location=\v!left]

\setupdescription % check with old
  [\c!alternative=\v!left,
   \c!headstyle=\v!bold,
   \c!titlestyle=\v!bold,
  %\c!style=,
  %\c!color=,
  %\c!headcolor=,
  %\c!titlecolor=,
   \c!width=7\emwidth,
   \c!distance=\emwidth,
   \c!titledistance=.5\emwidth,
  %\c!hang=,
  %\c!sample=,
  %\c!align=,
  %\c!headalign=,
   \c!margin=\v!no,
   \c!before=\blank,
   \c!inbetween=\blank,
   \c!after=\blank,
   \c!indentnext=\v!yes,
   \c!indenting=\v!never,
   \c!titleleft=(,
   \c!titleright=),
  %\c!closesymbol=,
   \c!closecommand=\wordright,
   \c!display=\v!yes,
  %\c!command=,
   \c!titlecommand=,
   \c!expansion=\v!no,
  %\c!xmlsetup=,
  %\s!catcodes=,
   \c!title=\v!yes,
  %\c!text=,
   \c!define=\v!yes,
  ]

\appendtoks
    \ifempty\currentdescriptionparent
        \defineconstruction[\currentdescription][\currentdescriptionparent][\s!handler=\v!description,\c!level=1]%
    \else
        \defineconstruction[\currentdescription][\s!handler=\v!description,\c!level=1]%
    \fi
    % We can combine these but in tracing (or errors) using a different caller is nicer.
    \ifcstok{\descriptionparameter\c!define}\v!yes
        \protected\frozen\instance\edefcsname        \currentdescription\endcsname{\nameddescription[\currentdescription]}%
        \protected\frozen\instance\edefcsname\e!start\currentdescription\endcsname{\startnameddescription[\currentdescription]}%
        \protected\frozen\instance \defcsname \e!stop\currentdescription\endcsname{\stopnameddescription}%
    \fi
\to \everydefinedescription

\protected\defcsname\??constructioninitializer\v!description\endcsname
  {\let         \currentdescription              \currentconstruction
   \enforced\let\constructionparameter           \descriptionparameter
   \enforced\let\constructionnamespace           \??description
   \enforced\let\detokenizedconstructionparameter\detokenizeddescriptionparameter
   \enforced\let\letconstructionparameter        \letdescriptionparameter
   \enforced\let\useconstructionstyleandcolor    \usedescriptionstyleandcolor
   \enforced\let\setupcurrentconstruction        \setupcurrentdescription
   \ifcstok{\constructionparameter\c!title}\v!yes
     \c_strc_constructions_title_state\conditionaltrue
   \else
     \c_strc_constructions_title_state\conditionalfalse
   \fi}

% We keep the command variant around but rather would move to the
% start-stop one. Also, passing the title as argument has some
% history so we need to keep that as well.

% \startdescription [reference]                text \stopdescription
% \startdescription [reference]{title}         text \stopdescription
% \startdescription [title=,title=,reference=] text \stopdescription

% A bit over the top, the optional title but mkii has it too.

\tolerant\permanent\protected\def\startnameddescription[#1]#*[#S#2]%
  {\begingroup
   \strc_constructions_initialize{#1}%
   \ifhastok={#2}%
     \expandafter\strc_descriptions_start_setups
   \orelse\ifconditional\c_strc_constructions_title_state
     \expandafter\strc_descriptions_start_title
   \else
     \expandafter\strc_descriptions_start_reference
   \fi[#2]}

% we could use this:
%
% \def\strc_descriptions_preset
%   {\setdescriptionparameter\c!label{\descriptionparameter\c!text}%
%    \resetdescriptionparameter\c!bookmark
%    \resetdescriptionparameter\c!list
%    \resetdescriptionparameter\c!referencetext}

\protected\def\strc_descriptions_start_setups[#S#1]%
  {\strc_constructions_register[][\c!reference=,\c!title=,\c!bookmark=,\c!list=,\c!referencetext=,#1]%
   \csname\??constructionstarthandler\currentconstructionhandler\endcsname}

\protected\tolerant\def\strc_descriptions_start_title[#1]#*#=%
  {\strc_constructions_register[][\c!reference={#1},\c!title={#2},\c!bookmark=,\c!list=,\c!referencetext=]%
   \csname\??constructionstarthandler\currentconstructionhandler\endcsname}

\protected\def\strc_descriptions_start_reference[#1]%
  {\strc_constructions_register[][\c!reference={#1},\c!title=,\c!bookmark=,\c!list=,\c!referencetext=]%
   \csname\??constructionstarthandler\currentconstructionhandler\endcsname}

\permanent\protected\def\stopnameddescription
  {\csname\??constructionstophandler\currentconstructionhandler\endcsname}

% \description [reference]         text \par
% \description [reference] {title} text \par

\tolerant\permanent\protected\def\nameddescription[#1]#*[#S#2]%
  {\begingroup
   \strc_constructions_initialize{#1}%
   \ifhastok={#2}%
     \expandafter\strc_descriptions_command_setups
   \orelse\ifconditional\c_strc_constructions_title_state
     \expandafter\strc_descriptions_command_title
   \else
     \expandafter\strc_descriptions_command_reference
   \fi[#2]}

\protected\def\strc_descriptions_command_setups[#S#1]%
  {\strc_constructions_register[][\c!label={\descriptionparameter\c!text},\c!reference=,\c!title=,\c!bookmark=,\c!list=,\c!referencetext=,#1]%
   \csname\??constructioncommandhandler\currentconstructionhandler\endcsname}

\protected\tolerant\def\strc_descriptions_command_title[#1]#:#*#=%
  {\strc_constructions_register[][\c!label={\descriptionparameter\c!text},\c!reference={#1},\c!title={#2},\c!bookmark=,\c!list=,\c!referencetext=]%
   \csname\??constructioncommandhandler\currentconstructionhandler\endcsname}

\protected\def\strc_descriptions_command_reference[#1]%
  {\strc_constructions_register[][\c!label={\descriptionparameter\c!text},\c!reference={#1},\c!title=,\c!bookmark=,\c!list=,\c!referencetext=]%
   \csname\??constructioncommandhandler\currentconstructionhandler\endcsname}

%D Handlers:

\letcsname\??constructionmainhandler   \v!description\expandafter\endcsname\csname\??constructionmainhandler   \v!construction\endcsname
\letcsname\??constructioncommandhandler\v!description\expandafter\endcsname\csname\??constructioncommandhandler\v!construction\endcsname
\letcsname\??constructiontexthandler   \v!description\expandafter\endcsname\csname\??constructiontexthandler   \v!construction\endcsname

\protected\defcsname\??constructioncommandhandler\v!description\endcsname
  {\dowithpar
     {\csname\??constructionstarthandler\v!construction\endcsname}%
     {\csname\??constructionstophandler \v!construction\endcsname\endgroup}}

\protected\defcsname\??constructionstarthandler\v!description\endcsname
  {\dogotopar
     {\csname\??constructionstarthandler\v!construction\endcsname}}

\protected\defcsname\??constructionstophandler\v!description\endcsname
  {\csname\??constructionstophandler\v!construction\endcsname
   \endgroup}

%D For historic reasons we have (from now on undocumented):

\definedescription
  [tab]
  [\c!alternative=\v!left,
   \c!headstyle=\v!normal,
   \c!headcolor=,
   \c!style=\v!normal,
   \c!color=,
   \c!width=\v!broad,
   \c!sample=\kern4\emwidth, % was \hskip but that no longer is okay
   \c!before=,
   \c!after=]

\permanent\protected\def\setuptab{\setupdescription[tab]} % for old times

%D Maybe we should remove this definition.

\protect \endinput