latex template

\documentclass{article}

\usepackage[T1]{fontenc}
\usepackage{array}
\usepackage{graphicx}

\usepackage{custom}

% Uncomment for a formal submission: one line strips every draft-only element
% this package adds, leaving only the manuscript prose.
% \setfinal

% hyperref is loaded by custom.sty; configure project-specific options here.
\hypersetup{
  colorlinks=true,
  linkcolor=blue,
  filecolor=magenta,
  urlcolor=cyan,
  pdftitle={custom.sty command reference},
  pdfauthor={Wei},
  bookmarksdepth=3
}

% Per-author comment shorthands, same two forms as \wei.
\newauthornote{\alice}{Alice}{teal}

% --- helpers used only by this demo, not part of custom.sty -------------------
\newcommand{\bs}{\textbackslash}
\newcommand{\sig}[1]{\texttt{\footnotesize #1}}
\newenvironment{cmdtable}{%
  \par\smallskip\noindent
  \begin{tabular}{@{}>{\raggedright\arraybackslash}p{0.45\linewidth}
                    >{\raggedright\arraybackslash}p{0.51\linewidth}@{}}
}{%
  \end{tabular}\par\smallskip
}

\title{\texttt{custom.sty} --- command reference and demo}
\author{Wei}
\date{v0.8, 2026-07-30}

\begin{document}
\maketitle

This document is the reference for \texttt{custom.sty}: \cref{sec:index} indexes
every command the package defines, and the sections after it render each one in
context. Compiling as-is shows the draft state, with every annotation visible.
Uncommenting \sig{\bs setfinal} in the preamble shows the submission build
instead, in which every annotation disappears and only the prose remains.

\section{Draft and final builds}
\label{sec:draft-final}

Everything this package adds on top of your prose is draft-only, and answers to
one of three switches. Each macro reads its switch when it is used, so you can
flip any of them in the preamble after \sig{\bs usepackage\{custom\}}, or even
part-way through the document.

\begin{cmdtable}
\sig{\bs setfinal}
  & Master switch. Strips every draft-only element at once. Put it in the
    preamble for a formal submission. \\
\sig{\bs setdraft}
  & Shows them all again. This is the default state, so you only need it to undo
    \sig{\bs setfinal} part-way through a document. \\
\sig{\bs setboolean\{showcomments\}\{false\}}
  & Hides only \sig{\bs wei}, \sig{\bs mynote}, \sig{\bs quotenote},
    \sig{\bs todo}, \sig{\bs ai}. \\
\sig{\bs setboolean\{showrevisions\}\{false\}}
  & Hides only \sig{\bs revision} and \sig{\bs revisionlog}. \\
\sig{\bs setboolean\{showdrafttext\}\{false\}}
  & Hides only the decoration of \sig{\bs unsure}, \sig{\bs ph}, \sig{\bs say}. \\
\end{cmdtable}

The three groups are separate because a revised submission often keeps one and
drops another: reviewers should see the revision log with every todo and AI
prompt already stripped.

No text is ever thrown away. An annotation that wraps a span of your prose loses
its tag and keeps the span, \sig{\bs unsure\{text\}} keeps the text and loses the
orange bold and the footnote, \sig{\bs ph\{hint\}} keeps the hint and loses the
brackets, and \sig{\bs say[concept]\{text\}} keeps the text and loses the tag.
Because \sig{\bs unsure} and \sig{\bs ph} both mean ``this is not finished yet'',
each one still raises a warning naming its input line in a final build, so the
log tells you what is unfinished rather than shipping it quietly.

\section{Command index}
\label{sec:index}

\subsection*{Symbols and indicators}

\begin{cmdtable}
\sig{\bs gcheck} & green checkmark: \gcheck \\
\sig{\bs cmark}  & teal check: \cmark \\
\sig{\bs xmark}  & red cross: \xmark \\
\end{cmdtable}

\subsection*{Numeric change indicator}

\begin{cmdtable}
\sig{\bs change\{pct\}\{sign\}}
  & Percentage change, sign \texttt{+} up, \texttt{-} down, \texttt{0} flat:
    \change{2.15}{+} \change{2.15}{-} \change{0}{0} \\
\sig{\bs change\{pct\}\{sign\}\{style\}}
  & Style \texttt{-} notes it (smaller, faded), \texttt{+} stresses it (bold):
    \change{2.15}{+}{-} \change{2.15}{+}{+} \\
\sig{\bs change[old,new]}
  & Percentage and sign computed from the two values: \change[100,105]
    and \change[200,180] \\
\sig{\bs change[old,new]\{\}\{\}\{style\}}
  & Same, with a style: \change[100,105]{}{}{-} \change[100,105]{}{}{+} \\
\sig{\bs improved\{pct\}}
  & Shorthand for an unconditional gain: \improved{2.15} \\
\end{cmdtable}

\subsection*{Todo lists}

\begin{cmdtable}
\sig{\bs begin\{todolist\}}
  & Checklist environment; a bare \sig{\bs item} is an open task. \\
\sig{\bs item[\bs done]}
  & Completed. \\
\sig{\bs item[\bs wip]}
  & In progress. \\
\sig{\bs item[\bs wontfix]}
  & Abandoned. \\
\end{cmdtable}

\subsection*{Inline annotations}

\begin{cmdtable}
\sig{\bs unsure\{text\}}
  & Wording you are not confident in: bold orange, plus a footnote reading
    ``Unsure wording, please finalize.'' \\
\sig{\bs unsure\{text\}[footnote]}
  & Same, with your own footnote text. \\
\sig{\bs ph\{hint\}}
  & Placeholder for a value or name you still owe the reader: \ph{hint} \\
\sig{\bs ph\{\}}
  & Placeholder with no hint: \ph{} \\
\end{cmdtable}

\subsection*{Collaboration and review}

\begin{cmdtable}
\sig{\bs wei\{comment\}}
  & A loose remark about the surrounding paragraph. \\
\sig{\bs wei\{quoted\}\{comment\}}
  & The same remark pinned to a span, which is bracketed in the author colour. \\
\sig{\bs mynote\{author\}\{text\}\{col\}}
  & The generic loose note behind \sig{\bs wei}, taking any \texttt{xcolor}
    colour. \\
\sig{\bs quotenote\{author\}\{span\}\{text\}\{col\}}
  & The generic pinned note, for a one-off author needing no shorthand. \\
\sig{\bs newauthornote\{\bs cmd\}\{Name\}\{col\}}
  & Defines a per-author shorthand carrying both forms at once. \\
\sig{\bs todo\{text\}}
  & An action item rather than a comment. The tag always leads with
    \texttt{TODO}. \\
\sig{\bs todo[label]\{text\}}
  & Appends a non-default label and takes its colour from it. Matching ignores
    case: \texttt{FIXME} and \texttt{BUG} are red, \texttt{NOTE},
    \texttt{LATER} and \texttt{HOLD} are gray, anything else is orange. \\
\sig{\bs todo[label]\{quoted\}\{text\}}
  & The same item pinned to a span, quoting the span first exactly as
    \sig{\bs wei} and \sig{\bs ai} do. \\
\sig{\bs ai\{quoted\}\{instruction\}}
  & Hands a span to an AI with a prompt, marked by a robot icon. The default
    state means apply it now. \\
\sig{\bs ai[hold]\{quoted\}\{instruction\}}
  & Parks the request for later instead of acting on it. \\
\end{cmdtable}

\subsection*{Revision trace}

\begin{cmdtable}
\sig{\bs revision[date]\{text\}}
  & Records one line of the revision history. Prints nothing where you write
    it. \\
\sig{\bs revision\{text\}}
  & The same, inheriting the last date written above it. \\
\sig{\bs revisionlog}
  & Prints every entry registered before it, as one dated list. \\
\sig{\bs revisionlogname}
  & The log heading, ``Revisions'' by default. Rename it with
    \sig{\bs renewcommand}. \\
\end{cmdtable}

\subsection*{Boxes and structure}

\begin{cmdtable}
\sig{\bs begin\{graybox\}}
  & Light gray background, no border, for multi-paragraph content. \\
\sig{\bs grayboxtext\{text\}}
  & One-shot wrapper around the same box. \\
\sig{\bs say[concept]\{text\}}
  & Labels a paragraph with the concept it carries. The label defaults to
    ``Concept''. \\
\end{cmdtable}

\subsection*{Cross-references}

\begin{cmdtable}
\sig{\bs cref\{label\}}
  & Reference with an abbreviated type name (Fig., Tab., Eq., \S, App., Alg.),
    preconfigured by \texttt{custom.sty}. \\
\sig{\bs Cref\{label\}}
  & The same at the start of a sentence. \\
\end{cmdtable}

\section{Introduction}

\say[how to use say cmd]{
Basically, if you want to write your paper more structured, every paragraph or
several paragraphs is telling a specific concept or idea, you can use the say
command to clearly introduce and explain these concepts. For example, I would
use a say command in introduction section to introduce the background, a say
command to introduce the main research question, and a say command to introduce
the methodology.
}

This is a concise summary of your research, highlighting the key objectives,
methods, \ph{sth similar}, and conclusions. \wei{This is a comment from Wei.}

\subsection{Collaborating with an AI reviewer}

Use \sig{\bs ai} to hand a span of text to an AI together with an instruction:
quote what you want acted on and say what to do. By default the AI should apply
it now: \ai{The quick brown fox jumps over the lazy dog.}{rewrite in a formal
academic tone} Mark a request as \texttt{[hold]} to park it for later instead of
acting: \ai[hold]{Our method is 10x faster.}{verify against the results table
before keeping}

\subsection{Commenting on a quoted span}

\sig{\bs wei} keeps its original one-argument form for a remark about the
paragraph as a whole, \wei{this is the classic form.} and gains a two-argument
form that is the human sibling of \sig{\bs ai}: quote the span you are
commenting on, then say what you think about it.
\wei{Our method is 10x faster.}{this number came from the old run, recheck it}
Give any other author the same pair of forms with \sig{\bs newauthornote}:
\alice{The dataset contains 1M images.}{closer to 1.2M after dedup} and
\alice{Alice can still write a loose note too.}
For a one-off author who does not need a shorthand, call the generic macro
directly: \quotenote{Bob}{Sampling was uniform.}{stratified, actually}{orange!80!black}

\subsection{Action items}

\todo{Write something worthwhile here.} \todo[fixme]{Tighten this paragraph
before submission.} \todo[NOTE]{Consider citing the 2024 survey here.}
\todo[hold]{Add a figure illustrating the main concept.}

An action item can also be pinned to the span it is about, quoting the span
first and saying what to do second, exactly as \sig{\bs wei} and \sig{\bs ai}
do: \todo[fixme]{Our method is 10x faster than the baseline.}{revise this claim}
and parked the same way: \todo[hold]{We evaluate on three datasets.}{decide
whether to keep this}

\subsection{Unfinished wording and placeholders}

Here you can introduce the background, motivation, and purpose of your research.
\unsure{This is a long piece of unsure wording that should break across multiple
lines, demonstrating that the bold orange highlight from \sig{\bs unsure} flows
naturally and does not prevent line breaking.}

I feel sleepy every day. \unsure{Yes, maybe.}[Maybe I should have.]

\begin{table}[h]
\centering
\begin{tabular}{|c|c|c|c|c|}
\hline
Item & Quantity & Normal & Noting & Stressing \\
\hline
A & 10 & 25.50~\change{2.15}{+} & 25.50~\change{2.15}{+}{-} & 25.50~\change{2.15}{+}{+} \\
B & 15 & 30.75~\change{3}{-}    & 30.75~\change{3}{-}{-}    & 30.75~\change{3}{-}{+} \\
C & \ph{8}  & 45.00~\change{0}{0}    & 45.00~\change{0}{0}{-}    & 45.00~\change{0}{0}{+} \\
\hline
\multicolumn{2}{|c|}{\small auto from [old,new]}
  & 105~\change[100,105]      & 180~\change[200,180]{}{}{-} & 50~\change[50,50]{}{}{+} \\
\hline
\end{tabular}
\caption{Demo table showing \sig{\bs change} variants: normal, noting (smaller, faded), stressing (bold).}
\label{tab:change-demo}
\end{table}

\subsection{Using cleveref (preconfigured in custom.sty)}
\label{sec:cleveref-demo}

Single references shrink to abbreviations: see \cref{tab:change-demo} for the
change-style demo, and \cref{sec:cleveref-demo} for this subsection. At the
start of a sentence use the capitalised form: \Cref{tab:change-demo} shows
three variants. Multiple labels of the same type collapse automatically:
\cref{tab:change-demo,sec:cleveref-demo} renders with a single prefix.

\subsection{Lists and boxes}

\begin{itemize}
  \item Immediate plan of action.
  \begin{todolist}
  	\item[\done] Frame the problem
  	\item Write solution
  	\item[\wontfix] profit
  \end{todolist}
\end{itemize}

\begin{todolist}
  \item[\done]    Frame the problem
  \item[\wip]     Draft the solution
  \item           Write tests
  \item[\wontfix] Profit
\end{todolist}

\grayboxtext{a quotation text in a gray box}

\section{Recording revisions}

Write \sig{\bs revision} beside the change it describes, or keep the whole batch
together at the end. Either way it prints nothing where you write it, and
\sig{\bs revisionlog} collects every entry registered above it into one dated
list. The date is optional and sticky: an entry that omits it inherits the last
date written above, so you type the date once per working session. Before any
date is given, entries fall back to the compile date, and nothing is ever
restamped on a later build.

\revision[2026-07-30]{unify the figures and plots with Avenir Next}
\revision{rename router to estimator in the text and in the figures, along with
the near terminology: weak-skipping estimator, weak-conditioned estimator,
pre-weak and post-weak estimator}
\revision[2026-07-27]{pin every annotation to a quoted span, and give
\texttt{\bs ai} a robot icon}
\revision{add the figstyle kit, sharing one palette across TikZ and matplotlib}

Four \sig{\bs revision} lines sit in this section's source, between the two
paragraphs you are reading, and none of them printed anything there. They
produce the log below. Note that the two sharing a date are grouped under it,
and that entries print in source order rather than being sorted.

\revisionlog

\end{document}