DOCSEARCHbyAlgolia
Submit Docs

latex-advice

repository·master·Indexed 23 days ago

https://github.com/dspinellis/latex-advice

A collection of best practices and advice for writing high-quality, maintainable, and professional scientific documents using LaTeX. The guide focuses on technical workflows, version control, build automation, and maintainability for researchers in fields such as computer science, engineering, mathematics, and physics.

Tokens
4.2K
Snippets
6
Records
19
Agent score
30%

What's inside latex-advice

  1. Overview of LaTeX advice for scientific writing

    master
    This project provides a collection of best practices for writing scientific documents (books, papers, theses) using LaTeX. It focuses on technical workflows, maintainability, and automation rather than English writing style or TeX programming itself. The advice is intended for researchers in fields like computer science, engineering, mathematics, and physics.

  2. Automate the LaTeX document build

    master

    Ensure your document can be built with a single command to avoid using outdated files and to facilitate teamwork. Recommended tools include:

    • latexmk: A standard tool bundled with most LaTeX distributions. Highly recommended for handling multiple passes.
    • BSD Owl: A set of scripts for build automation.
    • SCons: A build system using Python scripts (typically named SConstruct).
    • Unix make: The standard make command, though expressing complex multi-pass requirements can be difficult.

  3. Use style files for document formatting

    master
    Use style files provided by publishers or conference organizers to ensure your document meets their specific formatting and reference requirements. Using the official template helps minimize rework and ensures your document looks as it will in its published form.

  4. Avoid explicit formatting and use semantic commands

    master

    Instead of using explicit font commands (like \textbf or \textit) for general text styling, use semantic commands that describe the purpose of the text. This allows you to change the styling globally by modifying a single definition.

    Example: Defining a custom command for findings

    \newcommand{\finding}[1]{\textbf{#1}}

    Example: Defining a custom environment for licenses

    \newenvironment{license}{\verbatim\scriptsize}{\normalsize\endverbatim}
    \newcommand{\finding}[1]{\textbf{#1}}

\newenvironment{license}{\verbatim\scriptsize}{\normalsize\endverbatim}

  5. Typography and Text Formatting

    master

    Follow these rules for professional typography:

    • Dashes: Use --- for an em-dash (no spaces around it) and -- for an en-dash (used for number ranges like 2009--2015).
    • Emphasis: Avoid underlining. Use bold or italics instead. For abbreviations, use \textsc{...} (small caps).
    • Lists: For describing elements, use the description environment instead of itemize.
    • Ellipsis: Use \dots for the ellipsis symbol.
    • Footnotes: Place footnotes after punctuation symbols.
    • Code/Algorithms:
      • Use algorithmicx for pseudo-code.
      • Use listings (simple) or minted (advanced/nicer) for source code snippets. Ensure code does not exceed paragraph width.

  6. Apply LaTeX typesetting best practices

    master

    Follow these rules to ensure high-quality typography and maintainable LaTeX source code:

    • Prevent line breaks before references: Use a tilde (~) before \cite, \ref, etc.
      • Example: Some also use logging statements~\cite{Spi06e}.
    • Handle non-sentence ending periods: Place a backslash (\) after a period that does not end a sentence to prevent incorrect spacing.
      • Example: In 1962 Watson et al.\ famously found ….
    • Avoid math mode for plain text effects: Use \textsubscript{} and \textsuperscript{} instead of math mode \( ... \) for subscripts and superscripts in text.
      • Example: RQ\textsubscript{2} instead of \(RQ_2\).
    • Manage quotation marks:
      • Use matching single-opening (‘ or ‘‘) and single-closing (’ or ’’) characters instead of the keyboard double quote (").
      • Alternatively, use the \enquote{} macro from the csquotes package to handle language-specific quotes and nesting automatically.
    • Use modern font style commands: Prefer local font style commands like \texttt{}, \textsc{}, or \textbf{} over old switches like {\tt }, {\sc }, or {\bf }.

  7. Best practices for Figures and Floats

    master

    Figures

    • Format: Prefer vector graphics (PDF) over bitmaps (JPEG/PNG) to ensure scalability.
    • Consistency: Use the same font across all figures and scale them to match the document's font size.
    • Captions: Do not include a separate figure title; the caption serves this purpose. Label all axes.

    Floats

    • Environments: Use figure or table environments to allow large elements to float.
    • Centering: Use \centering inside the environment instead of the center environment to avoid extra vertical space.
    • Placement: Reference all floats in the text and place the float in the document before its first reference.
    • Caption Position: Generally, place table captions above the table and figure captions below the figure.

  8. Best practices for writing Mathematics in LaTeX

    master

    To ensure high-quality mathematical typesetting, follow these rules:

    • Math Mode: Always use LaTeX's math mode for all formulas and symbols. For inline math, prefer \( and \) delimiters over the TeX $ style.
    • Bracketing: Use balanced \left and \right commands so that brackets (parentheses, braces, etc.) automatically scale to the height of the content.
    • Operators:
      • Use built-in commands for supported operators (e.g., \mod, \max, \sin).
      • For unsupported operators, use \DeclareMathOperator from the amsmath package.
      • For multi-character variable names, use \mathit{...} or \mathrm{...} to avoid incorrect spacing.
      • Use roman type for non-index descriptive subscripts (e.g., x_{\mathrm{max}}).
    • Structure: Indent elements and break lines to express logical structure, keeping operators as the first character on a new line.
    • Punctuation: Equations are part of sentences. End them with a period or comma as appropriate, and use a thin space \, before the punctuation to prevent it from looking cramped.

  9. Manage bibliographic references in LaTeX

    master

    Automate your bibliography by using BibTeX or Biber. Create centrally-managed .bib files and include them in your document using the \bibliography command.

    Best Practices for Citations:

    • Use \cite{key1,key2} to group multiple references in a single command.
    • To reference specific pages or chapters, use square brackets: \cite[p.~8]{LR89}.
    • For author-year citations, use the natbib or BibLaTeX packages with commands like \citet, \citep, and \citeauthor.

    Best Practices for BibTeX Entries:

    • Title Capitalization: Use title case (e.g., The Elements of Programming Style). To preserve specific capitalization (like acronyms), wrap the character in braces: The {C} Programming Language.
    • DOI over URL: Prefer using the doi field over a url field. When using doi, do not include the resolution prefix (e.g., use doi = {10.1371/journal.pone.0294946} instead of https://doi.org/...).
    • Consistent Keys: Use short, derivable keys. A recommended scheme is:
      • Single author: First three letters of surname + last two digits of year (e.g., Ker08).
      • Multi-author: Up to four initials of surnames + last two digits of year (e.g., DMG07).
      • Clashes: Append a, b, c, etc.
    • Special Characters: Use LaTeX escapes for non-ASCII characters in author names (e.g., \'{e}) if not using Biber with Unicode support.

  10. Format numbers and units with siunitx

    master

    To comply with NIST and SI standards (e.g., placing a thin non-breaking space between a number and its unit), use the siunitx package. This package also handles long numbers with thin-space decimal separators and proper negative signs.

    Key commands:

    • \qty{value}{unit}: For quantities with units.
    • \num{value}: For formatting numbers.
    • \SI{value}{unit}: Alternative for SI units.
    • \SIrange{low}{high}{unit}: For ranges.
    • \SIlist{v1; v2; ...}{unit}: For lists of values.
    It took \qty{7146}{s} to load a \qty{134}{\gibi\byte} file over a
\qty{200}{\mebi\bit} connection over a distance of \qty{9500}{\km}. 
During the transfer \num{12345} packets were dropped.
The ambient temperature was \qty{-35}{\degreeCelsius}.

% Other siunitx examples
\SI{90}{\percent}, \SI{45}{\degreeCelsius}, \SIlist{5; 10; 15}{\milli\metre}, \SIrange{512}{1024}{\mebi\byte}

  11. Create professional Tables

    master

    Avoid using vertical rules (|) or excessive horizontal rules (\hline). Instead:

    • Alignment: Align numbers to the right, text to the left, and single symbols to the center. Use siunitx to align decimals.
    • Source Formatting: Use hard tabs before each column's & separator so columns align visually in the .tex source file.
    • Long Labels: If column labels are long, place them on separate lines, keeping them aligned with the data.
    • Horizontal Rules: Use the booktabs package for professional-looking rules: \toprule, \midrule, and \bottomrule.
    % Using booktabs for professional rules
\toprule
Header \\
\midrule
Table row 1 \\
Table row 2 \\
\bottomrule

% Aligning columns in source for readability
tr -cs  & 1     & \X    & --    & \V    & 1 \\
sort w  & 0     &       & --    & \X    & 0 \\

  12. Use LaTeX linters to find typesetting errors

    master

    Run the following linters on your document to identify and fix LaTeX anti-patterns (such as using ... instead of \dots):

    • LaCheck: Run using the lacheck command.
    • ChkTeX: Run using the chktex command.

    Users can define custom rules for these linters to enforce specific project guidelines or spelling consistency.