argdown.dtx

% \iffalse meta-comment
% !TeX program = xelatex
% !TeX encoding = utf-8
%<*internal>
\begingroup
%</internal>
%<*install>
\input{l3docstrip.tex}
\keepsilent
\askforoverwritefalse
\preamble
-------------------------------------------------------------------------------

An argdown parser for LaTeX

Copyright (C) 2022 by Felix Kopecky

This work consists of the file argdown.dtx 
         and the derived files argdown.sty and
                               argdown.pdf.

It may be distributed and/or modified under the conditions of the
LaTeX Project Public License (LPPL), either version 1.3c of this
license or (at your option) any later version. The latest version
of this license is at <http://www.latex-project.org/lppl.txt>.

This work is ``maintained'' (per LPPL maintenance status) by Felix Kopecky.

The development version can be found at
https://github.com/kopeckyf/argdown-l3
for those who are interested. Pull requests are welcome.

Please report any bugs or feature requests to 
https://github.com/kopeckyf/argdown-l3/issues

-------------------------------------------------------------------------------
\endpreamble
\declarepreamble\minimalpreamble
\endpreamble
\postamble
\endpostamble
\usedir{tex/latex/argdown}
\generate{\file{\jobname.sty}{\from{\jobname.dtx}{package}}}
%</install>
%<install>\endbatchfile
%<*internal>
\usepreamble\minimalpreamble
\usepostamble\defaultpostamble
\usedir{source/latex/argdown}
%\generate{\file{\jobname.ins}{\from{\jobname.dtx}{install}}}
\endgroup
%</internal>
%<*driver>
\documentclass{l3doc}
\usepackage{argdown}
\usepackage[british]{babel}
\usepackage{enumitem}
  \setlist[description]{font=\normalfont}
\usepackage{fontspec}
\usepackage{unicode-math}
  \setmainfont{TeX Gyre Pagella}
  \setmonofont{TeX Gyre Cursor}
  \setmathfont{TeX Gyre Pagella Math}
\usepackage{tcolorbox}
  \tcbuselibrary{listings}
  \newtcolorbox{hint}{sharp corners, colframe=blue!20, colback=blue!5}
  \newtcblisting[auto counter]{codeexample}[1]
    {%
      sharp corners, 
      title={Code example \thetcbcounter: #1},
      listing options={style=tcblatex, keywordstyle=\ttfamily},
    }

% Put things in the marginpar, similar to l3docs `function` environemnt.
\NewDocumentCommand{\ArgdownDocumentationMarginpar}{m}
  {
    \marginpar{%
      \raggedleft\ttfamily%
      \begin{tabular}{@{} l @{}}
        \toprule
        #1\\\bottomrule
      \end{tabular}}
  }
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
% \title{An \pkg{argdown} parser for \LaTeX}
% \author{Felix Kopecky\thanks{Please submit bug reports and feature requests to
% 		\protect\url{https://github.com/kopeckyf/argdown-l3/issues}.
% 	 }}
% \date{Development version from \today}
% \maketitle
% \frenchspacing
% \begin{documentation}
% \noindent This package contains a \LaTeX\ parser for the core 
% \href{https://argdown.org/}{Argdown} syntax. With this package, reconstructions
% of single arguments and statements that have been typed in Argdown documents 
% can be easily transferred to \LaTeX\ documents.
% 
% \begin{hint}
% While this package can parse core Argdown objects, such as single statements  
% and premise-conclusion structures, it does not support more complex Argdown
% objects, such as argument maps and dialectical relations between arguments.
% \end{hint}
% 
% \section{How \textit{\&} where to use this package}
% The package is loaded in a \LaTeX\ document with \cs{usepackage\{argdown\}}. 
% The package is loaded without any options, but settings can be customised via 
% \cs{argdownsetup}, explained below. It requires only core packages 
% \pkg{xparse} and \pkg{amsthm}.
%
% \begin{hint}
% Line breaks in the input do not have a special meaning in \LaTeX\ given its
% standard configuration. As \pkg{argdown} assigns meaning to line breaks
% (separation of items), it is necessary to configure \LaTeX\ to obey line 
% breaks. This is possible with \cs{obeylines}, but \cs{obeylines} does not work 
% in all surroundings. Examples where it does not work are footnotes or 
% \cs{fbox}. See \S\ref{sec:examples} for applications of \pkg{argdown} in
% example environments.
% \end{hint}
% 
% \begin{function}{\argdown}
%   \begin{syntax}
%     \cs{argdown} \oarg{options} \marg{input in Argdown format}
%   \end{syntax}
% The \marg{input in Argdown format} allows any features from the 
% \href{https://argdown.org/syntax/}{Argdown syntax} within the current
% coverage of this package, described in \S\ref{sec:coverage}.
% The \oarg{options} are local settings applied to the current \cs{argdown} 
% call only. Identical options can be used globally for \cs{argdownsetup}.
% 
% \iffalse
%<*example>
% \fi
\begin{codeexample}{Basic usage}
\argdown[leftmargin=0pt]{
   (1) If Felix has apple crumble, he has a great day.
   (2) If Felix has a great day, he is motivated to work on the argdown parser.
   --
   $ (x\implies y) \land (y\implies z) \implies (x\implies z)$
   --
   (3) If Felix has apple crumble, he is motivated to work on the argdown parser.
}
\end{codeexample}
% \iffalse
%</example>
% \fi
% \end{function}
% 
% \begin{function}{\argdownsetup}
%    \begin{syntax}
%      \cs{argdownsetup} \marg{options}
%    \end{syntax}
% Set \marg{options} for Argdown globally, that is, for every \cs{argdown} 
% instance following the setting in the current scope. Please see 
% \S\ref{sec:options} for a full list of options.
% \end{function}
%
% \section{Features}\label{sec:features}
% \subsection{Argdown syntax coverage}\label{sec:coverage}
% Elements in argdown syntax are separated by a line break: writing \verb+(1)+
% at the start of a line will generate a new premise, but placing it elsewhere
% will not. 
% \subsubsection{Statements}
% \ArgdownDocumentationMarginpar{$\lbrack$ Statements$\rbrack$}
% \iffalse
%<*example>
% \fi
\begin{codeexample}{Theses: Usage for propositions, single theses, etc.}
\argdown[leftmargin=0pt]{[Uniqueness thesis] If a body of evidence justifies belief in one proposition, it does not justify belief in contrary propositions.} 
\end{codeexample}
% \iffalse
%</example>
% \fi
%
% \subsubsection{Premise-conclusion structures}
% \ArgdownDocumentationMarginpar{<Argument title>\\(1) Premise}
% \textit{Argument titles}
% \textit{Premises, rules of inferences and conclusions}
% \textit{Inference rules}
% 
% \subsection{Descriptions \textit{\&} localisation}
% \subsection{Labelling \textit{\&} referencing} 
%
% \subsection{List of all options}\label{sec:options}
% \begin{description}[style=nextline]
% \item[|leftmargin =| \meta{dimension}\hfill (initially \cs{leftmargin})] 
% Space between the left margin of the page and the \cs{argdown} block.
% \item[|rightmargin =| \meta{dimension}\hfill (initially \cs{rightmargin})] 
% Space between the right margin of the page and the \cs{argdown} block.
% \item[|labelwidth =| \meta{dimension}\hfill (initially \cs{labelwidth})] 
% Space reserved for the label of statements (premises and conclusions).
% \item[|labelsep =| \meta{dimension}\hfill (initially \cs{labelsep})] Space 
% between label of statements and its content.
% \item[|topsep =| \meta{dimension}\hfill (initially |0.5|\cs{topsep})] 
% Vertical space before and after an object (such as an argument or a statement).
% \item[|roisep =| \meta{dimension}\hfill (initially |0.5|\cs{topsep})] 
% Vertical space before and after the inference rule.
% \item[|itemsep =| \meta{dimension}\hfill (initially \cs{itemsep})] Vertical 
% space between subsequent premises and conclusions of an argument 
% reconstruction.
% \item[|descriptions =| \meta{boolean}\hfill (initially |false|)] Whether or 
% not to print descriptors for statements (such as “premise” and “conclusion”). 
% See below for the locale options.
% \item[|title~font =| \meta{font settings}\hfill (initially \cs{itshape})] 
% Font of the titles of arguments and statements.
% \item[|locale/argument =| \meta{string}\hfill (initially |Argument|)] The 
% descriptor of argument objects.
% \item[|locale/premise =| \meta{string}\hfill (initially |Premise|)] The 
% descriptor of premise objects.
% \item[|locale/conclusion =| \meta{string}\hfill (initially |Conclusion|)] The 
% descriptor of conclusion objects.
% \item[|locale/intermediateconclusion =| \meta{string} (init. 
% |Intermediate| |Conclusion|)] The descriptor of intermediate conclusion 
% objects.
% \end{description}
%
% \section{Examples}\label{sec:examples}
% 
% \subsection{Use in \pkg{beamer} frames}
%
% \subsection{Use in \pkg{tcolorbox} boxes}
%
% \end{documentation}
% \newpage
%
% \begin{implementation}
% \section{Implementation}
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%    \begin{macrocode}
%<@@=argdown>
%    \end{macrocode}
%    \begin{macrocode}
\RequirePackage{xparse, amsthm}
\ProvidesExplPackage {argdown} {2022-10-20} {alpha} {Argdown parser for LaTeX}
%    \end{macrocode}

%    \begin{macro}{\argdown}
% The command to call the parser in the document.
%    \begin{macrocode}
\NewDocumentCommand{\argdown}{O{}}
  {%
    \c_group_begin_token
    \keys_set:nn { argdown } { #1 }
    \obeylines
    \argdown_init:n
  }
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}{\argdownsetup}
% Customise settings globally.
%    \begin{macrocode}
\NewDocumentCommand{\argdownsetup}{m}{ \keys_set:nn { argdown } { #1 } }
%    \end{macrocode}
%    \end{macro}

% \begin{variable}[int]{
%    \l__argdown_*_seq,
%    \l__argdown_*_int,
%    \l__argdown_*_tl,
%    \l__argdown_*_bool,
%    \l__argdown_*_prop
%  }
%  Internal variables.
%    \begin{macrocode}
\seq_new:N \l__argdown_lines_seq
\int_new:N \l__argdown_current_position_int
\tl_new:N \l__argdown_statement_id_tl
\tl_new:N \l__argdown_scanned_tl
\tl_new:N \l__argdown_statement_name_tl
\bool_new:N \l__argdown_in_list_bool
\bool_new:N \l__argdown_in_theorem_bool
\bool_new:N \l__argdown_after_inference_bool
\bool_new:N \l__argdown_print_descriptions_bool
\prop_new:N \l__argdown_localisation_prop
%    \end{macrocode}
% \end{variable}

%    \begin{macrocode}
\keys_define:nn { argdown }
  {
    leftmargin .dim_set:N  = \l__argdown_list_leftmargin_dim,
    leftmargin .initial:n  = {\leftmargin},
    rightmargin .dim_set:N = \l__argdown_list_rightmargin_dim,
    rightmargin .initial:n = {\rightmargin},
    labelwidth .dim_set:N  = \l__argdown_list_labelwidth_dim,
    labelwidth .initial:n  = {\labelwidth},
    labelsep .dim_set:N    = \l__argdown_list_labelsep_dim,
    labelsep .initial:n    = {\labelsep},
    topsep .dim_set:N      = \l__argdown_list_topsep_dim,
    topsep .initial:n      = {0pt},
    roisep .dim_set:N      = \l__argdown_list_roisep_dim,
    roisep .initial:n      = {.5\topsep},
    itemsep .dim_set:N     = \l__argdown_list_itemsep_dim,
    itemsep .initial:n     = {\itemsep},
    descriptions .bool_set:N = \l__argdown_print_descriptions_bool,
    descriptions .initial:n  = {false},
    title~font .code:n       = {\cs_set:Nn \__argdown_title_font: {#1}},
    title~font .initial:n    = {\itshape},
    locale / argument .prop_put:N 
    	= \l__argdown_localisation_prop,
    locale / argument .initial:n 
    	= {Argument},
    locale / premise .prop_put:N 
    	= \l__argdown_localisation_prop,
    locale / premise .initial:n 
    	= {Premise},
    locale / conclusion .prop_put:N 
    	= \l__argdown_localisation_prop,
    locale / conclusion .initial:n 
    	= {Conclusion},
    locale / intermediateconclusion .prop_put:N 
    	= \l__argdown_localisation_prop,
    locale / intermediateconclusion .initial:n 
    	= {Intermediate~Conclusion},
  }
%    \end{macrocode}

%    \begin{macro}[int]{argdown@rgumentstyle, argdown@rgument, argdownst@tement}
% The theorem style to store arguments.
%    \begin{macrocode}
\newtheoremstyle{argdown@rgumentstyle}%
                {0.5\baselineskip plus 0.2\baselineskip}% Space above
                {0.5\baselineskip plus 0.2\baselineskip}% Space below
                {\normalfont}% Body font
                {}% Indent amount
                {\__argdown_title_font:}% Argument title font
                {:}% Punctuation after argument head
                {.5em}% Space after argument title
                {}% Head spec

\theoremstyle{argdown@rgumentstyle}
\newtheorem{argdown@rgument}
  {%
    \prop_item:Nn \l__argdown_localisation_prop {argument}%
  }

\newtheorem*{argdownst@tement}
  {%
    \tl_use:N \l__argdown_statement_name_tl
  }
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}{\argdown_init:n}
% Initialise parsing, and ensure grouping for \cs{obeylines}.
%    \begin{macrocode}
\cs_new:Npn \argdown_init:n #1
  {
    \argdown_parse:n { #1 }
    \c_group_end_token
  }
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}{\argdown_parse:n}
% Execute the parser.
%    \begin{macrocode}
\cs_new:Npn \argdown_parse:n #1
  { 
    \regex_split:nnN { \r } { #1 } \l__argdown_lines_seq
    \seq_remove_all:Nn \l__argdown_lines_seq {}
    \seq_clear_new:N \l__argdown_position_of_boundaries_seq
    \int_zero:N \l__argdown_current_position_int
    \seq_map_inline:Nn \l__argdown_lines_seq
      {
        \tl_if_head_eq_meaning:nNTF
        { ##1 }
        <
          {
            \seq_put_right:NV
            \l__argdown_position_of_boundaries_seq
            \l__argdown_current_position_int
          }
          {
            \tl_if_head_eq_meaning:nNT
            { ##1 }
            [
              {
                \seq_put_right:NV
                \l__argdown_position_of_boundaries_seq
                \l__argdown_current_position_int
              }
          }
        \int_incr:N \l__argdown_current_position_int
      }
    \seq_put_right:Nx \l__argdown_position_of_boundaries_seq
      { \int_eval:n {\seq_count:N \l__argdown_lines_seq }  }
    \int_zero:N \l__argdown_current_position_int
    \seq_map_inline:Nn \l__argdown_lines_seq
      {
        \int_gincr:N \l__argdown_current_position_int
        \tl_gset_rescan:Nnn \l__argdown_scanned_tl {} { ##1 }
        \exp_args:Nx \token_case_meaning:NnF 
          { 
            \tl_head:N \l__argdown_scanned_tl 
          }
          {
            < {  \__argdown_parse_titles:N \l__argdown_scanned_tl  }
            ( {  \__argdown_parse_statements:N \l__argdown_scanned_tl  }
            - {  \__argdown_parse_delimiters:N \l__argdown_scanned_tl  }
            [ {  \__argdown_parse_singletons:N \l__argdown_scanned_tl  }
          }
          {
            \bool_if:NTF \l__argdown_after_inference_bool
            {\__argdown_parse_roi:N \l__argdown_scanned_tl}
            {\tl_use:N \l__argdown_scanned_tl}
          }
      }
    \bool_if:NT \l__argdown_in_list_bool
      {
        \__argdown_end_list:
        \bool_set_false:N \l__argdown_in_list_bool
      }
    \bool_if:NT \l__argdown_in_theorem_bool
      {
        \__argdown_end_theorem:
        \bool_set_false:N \l__argdown_in_theorem_bool
      }
  }
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}[int]{\__argdown_parse_titles:N}
% Parses titles
%    \begin{macrocode}
\cs_new:Npn \__argdown_parse_titles:N #1
  {
    \bool_if:NT \l__argdown_in_list_bool
      {
        \__argdown_end_list:
        \bool_set_false:N \l__argdown_in_list_bool
      }
    \bool_if:NT \l__argdown_in_theorem_bool
      {
        \__argdown_end_theorem:
        \bool_set_false:N \l__argdown_in_theorem_bool
      }
    \tl_remove_once:Nn #1 { < }
    \tl_remove_once:Nn #1 { > }
    \mode_leave_vertical: 
    \__argdown_begin_theorem:n { #1 }
    \bool_set_true:N \l__argdown_in_theorem_bool
  }
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}[int]{\__argdown_parse_statements:N}
% Parse statements.
%    \begin{macrocode}
\cs_new:Npn \__argdown_parse_statements:N #1
  {
    \tl_clear:N \l__argdown_statement_id_tl
    \tl_map_inline:Nn #1
      {
        \str_case:nnF { ##1 }
          {
            { ( }  { }
            { ) }  { \tl_map_break: }
          }
          { \tl_put_right:Nn \l__argdown_statement_id_tl ##1 }
      }
    \bool_if:NF \l__argdown_in_list_bool
      {
        \__argdown_begin_list:
        \bool_set_true:N \l__argdown_in_list_bool
      }
    \item[(\tl_use:N \l__argdown_statement_id_tl)]
    \def\@currentlabel{(\tl_use:N \l__argdown_statement_id_tl)}
    \bool_if:NT \l__argdown_print_descriptions_bool
      {
        \bool_if:NTF \l__argdown_after_inference_bool
          {
            \seq_if_in:NxTF
            \l__argdown_position_of_boundaries_seq
              {
                \int_eval:n { \l__argdown_current_position_int }
              }
              {
                \prop_item:Nn \l__argdown_localisation_prop
                {conclusion}:\c_space_token
              }
              {
                \prop_item:Nn \l__argdown_localisation_prop
                {intermediateconclusion}:\c_space_token
              }
            }
            {
              \prop_item:Nn \l__argdown_localisation_prop
              {premise}:\c_space_token
            }
      }
    \tl_range:Nnn #1 {\tl_count:N \l__argdown_statement_id_tl + 3} { -1 }
    \bool_set_false:N \l__argdown_after_inference_bool
  }
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}[int]{\__argdown_parse_delimiters:N}
% Parse inference rules.
%    \begin{macrocode}
\cs_new:Npn \__argdown_parse_delimiters:N #1
  {
    \bool_if:NTF \l__argdown_in_list_bool
      {
        \__argdown_end_list:
        \__argdown_inference_rule:
        \bool_set_false:N \l__argdown_in_list_bool
      }
      {
        \__argdown_inference_rule:
        \__argdown_begin_list:
        \bool_set_true:N \l__argdown_in_list_bool
      }
    \bool_set_true:N \l__argdown_after_inference_bool
  }
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}[int]{\__argdown_parse_roi:N}
% Parse rules of inference.
%    \begin{macrocode}
\cs_new:Npn \__argdown_parse_roi:N #1
  {
    \bool_if:NTF \l__argdown_in_list_bool
      {
        \item[] \tl_use:N #1
      }
      {
        \c_group_begin_token
        \dim_set_eq:NN
        \l__argdown_list_topsep_dim
        \l__argdown_list_roisep_dim
        \__argdown_begin_list:
        \item[] \tl_use:N #1
        \__argdown_end_list:
        \c_group_end_token
      }
  }
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}[int]{\__argdown_parse_singletons:N}
% Parse single statements.
%    \begin{macrocode}
\cs_new:Npn \__argdown_parse_singletons:N #1
  {
    \tl_gclear:N \l__argdown_statement_name_tl
    \tl_greplace_all:Nnn #1 { ~ } { \c_space_token }
    \tl_map_inline:Nn #1
      {
        \str_case:nnF { ##1 }
          {
            { [ }  { }
            { ] }  { \tl_map_break: }
          }
          { \tl_gput_right:Nn \l__argdown_statement_name_tl ##1 }
      }
    \bool_if:NT \l__argdown_in_list_bool
      { \__argdown_end_list: }
    \bool_if:NT \l__argdown_in_theorem_bool
      { \__argdown_end_theorem: }
    \__argdown_begin_singleton:
    \tl_range:Nnn #1 {\tl_count:N \l__argdown_statement_name_tl + 3} { -1 }
    \__argdown_end_singleton:
  }
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}[int]{\__argdown_begin_list:}
% Inner list for premise-conclusion structures.
%    \begin{macrocode}
\cs_new:Nn \__argdown_begin_list:
  {
    \begin{list}
    {}
    {
      \leftmargin=\dim_use:N \l__argdown_list_labelwidth_dim
      \rightmargin=0pt
      \labelwidth=\dim_use:N \l__argdown_list_labelwidth_dim
      \labelsep=\dim_use:N \l__argdown_list_labelsep_dim
      \topsep=0pt
      \itemsep=\dim_use:N \l__argdown_list_itemsep_dim
      \partopsep=0pt
    }
  }
%    \end{macrocode}
%    \end{macro}

%    \begin{macro}[int]{\__argdown_end_list:, }
%    \begin{macrocode}
\cs_new:Nn \__argdown_end_list: { \end{list} }
\cs_new:Npn \__argdown_begin_theorem:n #1 
  { 
    \begin{argdown@rgument}[#1] 
    \mode_leave_vertical:
  }
\cs_new:Nn \__argdown_end_theorem: { \end{argdown@rgument} }
\cs_new:Nn \__argdown_begin_singleton: { \begin{argdownst@tement} }
\cs_new:Nn \__argdown_end_singleton:  { \end{argdownst@tement} }
\cs_new:Nn \__argdown_inference_rule: 
  { 
    \vskip-.5\baselineskip\noindent\hrulefill\par 
  }
%    \end{macrocode}
%    \end{macro}

%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \end{implementation}
% \PrintIndex