Notation & Conventions

Naming Conventions

Neural Sketch employs a consistent and intuitive naming system for all its $\LaTeX$ control sequences, ensuring ease of use and readability. All commands follow a camelCase structure and are clearly identified by the unique prefix \nsk<*>. This approach eliminates confusion, enabling you to quickly grasp each macro’s role at a glance.

For example, to create a basic diagram element (block), you simply use:

\nskBlock[...]

General Naming Structure

Each Neural Sketch command adheres to this general structure:

\nsk<Action>[<key-value pairs>]{<content>}

• Prefix \nsk clearly differentiates Neural Sketch macros from standard TikZ or LaTeX commands.
• <Action> intuitively describes the operation or object (e.g., Block, Container, Group).
• <Key-value pairs> within brackets [ ... ] control properties such as colors, dimensions, and positioning.
• <Content>, if applicable, is enclosed in curly braces { ... }, defining nested elements or grouped structures.

Macro-Based Design Philosophy

Neural Sketch diverges deliberately from TikZ’s traditional environment-based structure by adopting a macro-based approach. This strategic choice greatly simplifies nesting, modularization, and composability, particularly when creating complex diagrams or reusing structures across multiple illustrations.

Example: Grouping Elements

Neural Sketch uses macros to encapsulate grouped diagram components:

✅ Macro-based syntax (neural-sketch)

\nskGroup[<opts>]{
  <content>
}

🚫 Environment-based syntax (TikZ convention)

\begin{nskGroup}[<opts>]
  <content>
\end{nskGroup}

Why Prefer Macros? 🤔

Opting for macros over environments offers tangible benefits:

• Reduced Nesting 📐: Avoids deeply nested environments, maintaining clarity even in intricate diagrams.
• Improved Readability 📖: Macro-based syntax supports a cleaner, more declarative style.
• Enhanced Modularity 🔗: Easier to encapsulate reusable components or patterns.
• Scalable & Lightweight 🪶: Simplifies complex layout logic and keeps code succinct.

Styling Conventions

Neural Sketch maintains clear conventions for styling options and keys:

• Kebab-case (border-radius, fill-opacity) for key-value options within macros.
• PascalCase (nskBlock, nskContainer) for macro names.
• Colors are always prefixed with nsk and follow PascalCase (e.g., nskBlue, nskLightGray).

Example usage with clear styling conventions:

\nskBlock[
  fill=nskLightGray,
  border-radius=2mm,
  text-center={Central Node}
]

Recommended Workflow

When constructing diagrams, adhere to the following recommended workflow for maximum productivity and clarity:

\usepackage{neural-sketch}
\nskUseModule{*}

\nskSetStyle{
  block-fill = nskBlue,
  container-padding = 1cm
}

\begin{nskFigure}
  \nskContainer[
    text-north={Grouped Blocks}
  ]{
    \nskBlock[x=0, y=0, text-center={A}]
    \nskBlock[last-pos={right=1cm}, text-center={B}]
  }
\end{nskFigure}