Add initial documentation

langsci-affiliations.dtx

@@ -12,7 +12,7 @@
 ------------------------------------------------------------------------------
 
 langsci-affiliations collects, orders, and outputs author-affiliation pairs.
-It the property list data type from LaTeX3.
+It makes use of data types from LaTeX3.
 
 The package is aimed to be helpful to class authors, i.e. those who design
 and maintain document templates in publishing houses, universities, etc. The 
@@ -150,11 +150,11 @@ Please report any bugs or feature requests to
 % \end{description}
 % 
 % \end{function}
-
 % \end{documentation}
 % 
-% \begin{implementation}
+% \newpage
 % 
+% \begin{implementation}
 % \section{Implementation}
 %    \begin{macrocode}
 %<*package>
@@ -167,21 +167,31 @@ Please report any bugs or feature requests to
 \ProvidesExplPackage {langsci-affiliations}
 {2021-02-17} {1.0.0}
 {A LaTeX3 package to collect and order authors and affiliations}
+%    \end{macrocode}
 
-
+%    \begin{macro}{\ResolveAffiliations}
+% The top-level document command. It is grouped to keep assignments local.
+%    \begin{macrocode}
 \NewDocumentCommand{\ResolveAffiliations}{ O{} +m }
   {%
     \group_begin:
     \keys_set:nn { affiliations } { #1 }%
     \exp_args:No \affiliations_resolve:n { #2 }%
     \group_end:
   }
+%    \end{macrocode}
+%    \end{macro}
 
+%    \begin{macro}{\SetupAffiliations}
+% A command to define options.
+%    \begin{macrocode}
 \NewDocumentCommand{\SetupAffiliations}{ m } 
   {%
     \keys_set:nn { affiliations } { #1 } 
   }
-
+%    \end{macrocode}
+%    \end{macro}
+%    \begin{macrocode}
 \keys_define:nn { affiliations }
   {
     mark~style .tl_set:N
@@ -229,6 +239,24 @@ Please report any bugs or feature requests to
     input~affiliation~separator .initial:n
         = {;}
   }
+%    \end{macrocode}
+%    \begin{variable}[int]{
+%           \prop_put:Nxx,
+%           \prop_put:Nnx,
+%           \seq_set_split:Nvn,
+%           \l__affiliations_tmpa_clist, 
+%           \l__affiliations_tmpa_int, 
+%           \l__affiliations_affiliations_seq, 
+%           \l__affiliations_authors_seq, 
+%           \l__affiliations_names_seq, 
+%           \l__affiliations_tmpa_seq,
+%           \l__affiliations_tmpb_seq,
+%           \l__affiliations_tmpa_tl,
+%           \l__affiliations_tmpb_tl,
+%           \l__affiliations_output_prop,
+%           \l__affiliations_affiliations_prop}
+% Internal variants and variables
+%    \begin{macrocode}
 
 \cs_generate_variant:Nn \prop_put:Nnn { Nxx }
 \cs_generate_variant:Nn \prop_put:Nnn { Nnx }
@@ -243,7 +271,14 @@ Please report any bugs or feature requests to
 \seq_new:N \l__affiliations_tmpb_seq
 \tl_new:N \l__affiliations_tmpa_tl
 \tl_new:N \l__affiliations_tmpb_tl
-
+\prop_new:N \l__affiliations_output_prop
+\prop_new:N \l__affiliations_affiliations_prop
+%    \end{macrocode}
+%    \end{variable}
+%    \begin{variable}[int]{\l__affiliations_icons_prop}
+% The data for the |circled| mark style. Since this uses the \cs{char}, it is
+% only available in XeLaTeX.
+%    \begin{macrocode}
 \prop_const_from_keyval:Nn \l__affiliations_icons_prop
   {
      0 = \char"2460,  1 = \char"2461,  2 = \char"2462,  3 = \char"2463,  
@@ -252,10 +287,12 @@ Please report any bugs or feature requests to
     12 = \char"246C, 13 = \char"246D, 14 = \char"246E, 15 = \char"246F, 
     16 = \char"2470, 17 = \char"2471, 18 = \char"2472, 19 = \char"2473
   }
-
-\prop_new:N \l__affiliations_output_prop
-\prop_new:N \l__affiliations_affiliations_prop
-
+%    \end{macrocode}
+%    \end{variable}
+%    \begin{macro}[int]{\__affiliations_resolve_affiliations:}
+%    A helper macro to order affiliations. Is called by 
+%    \cs{affiliations_resolve:n}.
+%    \begin{macrocode}
 \cs_new:Npn \__affiliations_resolve_affiliations: #1#2
   {
     \clist_clear:N \l__affiliations_tmpa_clist
@@ -291,7 +328,12 @@ Please report any bugs or feature requests to
                       \l__affiliations_tmpa_clist
       }
   }
-
+%    \end{macrocode}
+%    \end{macro}
+%    \begin{macro}[int]{\__affiliations_output_affiliations:}
+%    A helper macro that outputs the list of affiliations, usually below 
+%    the list of authors.
+%    \begin{macrocode}
 \cs_new:Nn \__affiliations_output_affiliations:
   {
     \prop_map_inline:Nn \l__affiliations_affiliations_prop
@@ -317,7 +359,11 @@ Please report any bugs or feature requests to
         ##1 ~
       }
   }
-
+%    \end{macrocode}
+%    \end{macro}
+%    \begin{macro}[int]{\__affiliations_return_afil_text:n}
+%    A helper macro that returns the affiliation marks.
+%    \begin{macrocode}
 \cs_new:Npn \__affiliations_return_afil_text:n #1
   {
     \int_set:Nn \l__affiliations_tmpa_int { #1 }
@@ -342,7 +388,12 @@ Please report any bugs or feature requests to
         {none} { }
       }
   }  
+%    \end{macrocode}
+%    \end{macro}
 
+%    \begin{macro}[int]{\__affiliations_output_authors:}
+%    A helper macro to output the list of authors, with affiliation marks (if any).
+%    \begin{macrocode}
 \cs_new:Nn \__affiliations_output_authors:
   {
     \seq_clear:N \l__affiliations_tmpa_seq
@@ -366,7 +417,12 @@ Please report any bugs or feature requests to
                     {\l__affiliations_separator_between_mult_tl} 
                     {\l__affiliations_separator_between_last_two_tl}
   }
+%    \end{macrocode}
+%    \end{macro}
 
+%    \begin{macro}[int]{\affiliations_resolve:n}
+%    The main macro.
+%    \begin{macrocode}
 \cs_new:Npn \affiliations_resolve:n #1 
   {
     \seq_set_split:NVn \l__affiliations_names_seq 
@@ -426,6 +482,7 @@ Please report any bugs or feature requests to
       }
   }
 %    \end{macrocode}
+%    \end{macro}
 %    \begin{macrocode}
 %</package>
 %    \end{macrocode}