% Copyright (c) 2021 Magnus Lie Hetland
%
% Permission is hereby granted, free of charge, to any person obtaining a copy
% of this software and associated documentation files (the "Software"), to deal
% in the Software without restriction, including without limitation the rights
% to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
% copies of the Software, and to permit persons to whom the Software is
% furnished to do so, subject to the following conditions:
%
% The above copyright notice and this permission notice shall be included in all
% copies or substantial portions of the Software.
%
% THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
% IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
% FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
% AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
% LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
% OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
% SOFTWARE.

\documentclass[twocolumn, a4paper]{article}

\usepackage{lmodern}
\def\sfdefault{cmbr}
\def\ttdefault{cmtl}

\usepackage{skeldoc}

\usepackage{amsthm}
\newtheorem{thm}{Theorem}

% For discussing commmands:

\makeatletter
\ExplSyntaxOn

% Copied from http://ctan.uib.no/macros/latex/base/doc.dtx
% Protect when used in moving arguments.
{\catcode`\|=\z@ \catcode`\\=12 |gdef|bslash{\}}

\NewDocumentCommand \cs { m } {%
    \texttt{\bslash #1}%
}

\NewDocumentCommand \braces { +m } {%
    \string{#1\string}%
}

\NewDocumentCommand \pkg { o m } {
    \IfNoValueTF { #1 } {
        \textsf { #2 }
    } {
        \href{ #1 }{ \textsf { #2 } }
    }
}

\NewDocumentCommand \var { m } {
    $\langle$
    \textnormal{\textit{#1}}
    $\rangle$
}

\ExplSyntaxOff
\makeatother

% To illustrate the \skelpseudo command:

\usepackage{pseudo}

\title{\skelline{The \pkg{skeldoc} package is intended for incremental
document development, with commands that insert simplified placeholder
elements for missing parts, similar to \emph{skeleton screens}, optionally
with associated notes explaining the placeholders.}}

\author{\skelline[5cm]{The \pkg{skeldoc} package is written by Magnus Lie
Hetland.}}

\begin{document}
\maketitle

\begin{abstract}
    \skelpar[4]
\end{abstract}

\section{Introduction}

\skelpar[7]{All the skeleton commands are followed by an optional argument in
brackets, and one (also optional) in braces, like
\cs{skelfoo}\texttt{[\var{conf}]\braces{\var{note}}}. The first argument is
for limited local
configuration, setting keys relevant to the specific command. Each command
also lets you supply one such config value \emph{without} a key, leaving the
key implicit. For example, for \cs{skelline} (a single skeleton line), this is
\texttt{width} and for \cs{skelpar} (a single skeleton paragraph), it's
\texttt{lines}. So \cs{skelline[5cm]} is the same as
\cs{skelline[width\,=\,5cm]}. The \cs{skelpar} command also has the keys
\texttt{first-width}, \texttt{width} and \texttt{last-width}, to adjust the
various line widths.

The argument in braces is a \emph{note} associated with the skeleton element,
typeset using the \cs{skelnote} command, which places a number in the margin
and an note at the end of the document (or wherever the \cs{printskelnotes}
command is placed), with hyperlinks in both directions.

Beyond the keys available locally, there are several \emph{global} config
keys, which may be set using the \cs{skelset} command (which respects \TeX{}
groups, so such config may also be local, e.g., by wrapping the relevant part
of the document in braces). For example, one might use
\cs{skelset\braces{main-color\allowbreak\,=\,black}} to produce a look along
the lines of the \pkg[https://ctan.org/pkg/censor]{censor} package. Shared
defaults for the local keys may also be set in this way, generally using the
local key name with the type of element as a prefix; for example,
\texttt{par-lines} is used to set the default for the \texttt{lines} key of
the \cs{skelpar} command. There are also some other general keys, like
\texttt{main-color} and \texttt{full-width}. For an overview of the
configuration keys, please consult the source file, \texttt{skeldoc.sty}.}
\skelenum[3]
\noindent
\skelpar[3]

\section{\skelline}

\skelpar

\skelnote{It is possible to add notes in arbitrary parts of a document with
the \cs{skelnote} command. This could also be used as a simple to-do or
annotation mechanism. Note that \cs{skelnote} is designed so you can place it
before a paragraph or the like, and get the number positioned correctly. This
means it gobbles up any space that follows it. To avoid this, simply follow it
by an escaped space, for example, as in \texttt{\cs{skelnote}\braces{My
note}\cs{\char32}}.}
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
eirmod tempor invidunt ut labore et dolore magna aliquyam erat~\skelref{Here I'm
referring to something non-existent, with \cs{skelref}, whose implicit key is
\texttt{width}.}, sed diam voluptua.
\skelpar[2]
At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd
gubergren, no sea takimata sanctus est~\skelcite{And here is a missing
bibliographic reference, with \cs{skelcite}, whose implicit key is
\texttt{width}. You can also control the left and right braces (or whatever text
you wish to surround the citation with) using the \texttt{left} and
\texttt{right} keys.}.

\skelpar
\skelitems{The \cs{skelenum} and \cs{skelitems} commands produce skeleton
\emph{lists} (using \texttt{enumeration} and \texttt{itemize}). Their implicit
key is \texttt{items}, which controls the number of items, while
\texttt{item-lines} controls the number of lines per item.}
\noindent
\skelpar[4]

\begin{figure}
\skelfig[5cm]{Skeleton figures (\cs{skelfig}) have \texttt{height} as their
implicit key. The width may be modified using the \texttt{width} key.}
\skelcaption{Skeleton captions are best typeset using the special-purpose
\cs{skelcaption} command, rather than simply placing a \cs{skelpar} in a
normal \cs{caption}, at least if you intend to attach a note. This is because
captions are generally typeset more than once, in order to determine whether
to center them; \cs{skelcaption} prevents any attached note from being added
to the note list twice.

The implicit argument of \cs{skelcaption} is \texttt{lines}, and the other
keys are as for \cs{skelpar}, relying on the same defaults and global
configuration.}
\end{figure}%

\skelpar
\begin{equation}
    \skelline
\end{equation}
\skelpars[3]{Multiple skeleton paragraphs may be produced using the
\cs{skelpars} command, whose implicit key is \texttt{pars}, controlling
the number of paragraphs.}

\begin{table}
\skelcaption[1]{The \cs{skelcaption} command may be used for figures and
tables alike.}
\skeltabular[7]{The \cs{skeltabular} command produces a skeleton table
(specifically, a \texttt{tabularx}). The implicit key is \texttt{rows},
controlling the number of rows in the table. The \cs{tabcolsep} and
\cs{arraystretch} used can be set with the \texttt{colsep} and
\texttt{stretch} keys.}
\end{table}

\skelpar

\begin{thm}
    \skelpar[3]
\end{thm}
\begin{proof}
\skelpar
\end{proof}

\skelpar

\section{\skelline}

\skelpar
\skelpseudo[
    head={\pr{Lorem-Ipsum}(\id{dolor}, \id{sit}, \id{amet})},
]{The \cs{skelpseudo} command only works if the
\pkg[https://ctan.org/pkg/pseudo]{pseudo} package has been imported. (It is
not imported by the \pkg{skeldoc} package.) The implicit key is
\texttt{lines}, the number of lines to produce (in addition to the headline,
if any). By default, no headline is included, but one may be set using the
\texttt{head} key (e.g., using the \cs{pr} command from the
\pkg[https://ctan.org/pkg/pseudo]{pseudo} package, rather than \cs{hd},
because the \texttt{head} key handles the \cs{multicolumn} stuff itself; for
example, use
\texttt{head\,=\,\braces{\cs{pr}\braces{\var{name}}(\var{args})}}). The indent
pattern is set using the \texttt{newlines} key, which should be a
comma-separated list of newline commands as used by the
\pkg[https://ctan.org/pkg/pseudo]{pseudo} package (such as \cs{\bslash+} or
\cs{\bslash--}). This list is used round-robin as the lines progress. E.g., if
you want pseudocode without any indentation, simply use
\texttt{newlines\,=\,\cs{\bslash}}.}
\skelpar

\section{Discussion}

\skelpars[2]

\skelbib{The \cs{skelbib} command produces a skeleton bibliography, with the
number of items controlled by the implicit key \texttt{items}. The number of
lines per item is controlled by \texttt{item-lines}.}

\printskelnotes

\end{document}
