Build several documents from shared content.

Overview

Keep content separate from document presentation

Document Automation provides four SCons builders that convert TeX content into PDFs. The build script selects the document structure, style, metadata, and output options; the source files contain the research content.

Before you begin: Install and activate SIGCLEAR, then run sglicense-check to verify the Document Automation license.

Quick start

Build an article from a TeX source

Create paper.tex with the document content:

\begin{abstract}
This report summarizes the experiment.
\end{abstract}

\section{Method}
Describe the method and its results here.

Create SConstruct in the same directory:

from document import *

Article(
    'paper.pdf',
    'paper.tex',
    title='Experiment report',
    author='Research Team',
    maketitle=True
)

Run the build:

scons

SCons creates paper.pdf and rebuilds it when the source or build definition changes.

Main workflow

Generate synchronized editions from one source

Define several targets that share the same content. This build produces an internal report, a publisher-styled paper, and a marked review edition:

from document import *

Article(
    'internal-report.pdf',
    'paper.tex',
    package='sigclear/basic'
)

Article(
    'publication.pdf',
    'paper.tex',
    package='spwla'
)

Article(
    'publication-review.pdf',
    'paper.tex',
    option='review',
    package='spwla'
)

When paper.tex changes, one scons command updates every affected target. Add further Article, Slides, or Book targets when the same maintained material must be delivered in another structure or style.

Builders

Choose the structure of each output

Article, Slides, and Book accept the common arguments target, source, option, title, subtitle, proceedings, maketitle, author, institute, email, address, date, package, bib, and preamble.

Source definitions

Use one file, several files, or source directories

An Article or Slides source can be expressed in several equivalent forms:

# One source file
Article('paper.pdf', 'paper.tex')

# The matching paper.tex is inferred from paper.pdf
Article('paper.pdf')

# The default target and source are paper.pdf and paper.tex
Article()

# Several files
Article('paper.pdf', [
    'section1/paper.tex',
    'section2/paper.tex'
])

# A space-separated source string
Article('paper.pdf',
        'section1/paper.tex section2/paper.tex')

# A trailing slash selects paper.tex in each directory
Article('paper.pdf', 'section1/ section2/')

Slides supports the same source forms. Book also accepts these forms and can use dictionaries to define document structure. Diary is different: its source is a directory containing date-organized TeX notes.

Books

Define chapters, parts, and front or back matter

Use a dictionary when chapter titles should be supplied by the build definition:

chapters = {
    'Introduction': 'intro/paper.tex',
    'Methods': 'methods/',
    'Results': [
        'results-a/paper.tex',
        'results-b/paper.tex'
    ]
}

Book('research-book.pdf', chapters)

A key with a None value introduces a Part before the following chapters:

chapters = {
    'Background': None,
    'Introduction': 'intro/',
    'Implementation': None,
    'Methods': 'methods/'
}

For a complete book, group content under the recognized copyright, frontmatter, mainmatter, appendix, and backmatter keys:

book = {
    'copyright': 'copyright.tex',
    'frontmatter': {
        'Preface': 'preface.tex',
        'Acknowledgements': 'acknowledgements.tex'
    },
    'mainmatter': {
        'Introduction': 'intro/',
        'Data management': 'data/'
    },
    'appendix': {
        'Reference tables': 'appendix/'
    },
    'backmatter': {
        'About the authors': 'authors.tex'
    }
}

Book('book.pdf', book, title='Research handbook')

Options and metadata

Control review output, page size, and presentation ratio

Article('paper-a5.pdf', 'paper.tex', option='a5paper')
Slides('slides-wide.pdf', 'slides.tex', option='16x9')
Book('book-with-figures.pdf', 'chapters.tex', option='listfigs')

Use builder arguments for metadata that should be controlled by the output definition:

Article(
    'paper.pdf',
    'paper.tex',
    title='Measurement analysis',
    subtitle='Final report',
    author='A. Researcher',
    institute='Example Laboratory',
    email='researcher@example.org',
    date='September 2026',
    bib='references.bib',
    maketitle=True
)

Content interface

Write with a focused set of TeX commands

Content authors can use the standard structural commands supported across SIGCLEAR document outputs:

With option='review', wrap removed content in \old{...} and added content in \new{...}. Normal output hides old content and retains new content; review output marks both for comparison.

Classes and styles

Build with the supplied document formats

Document Automation supplies the myarticle, myslides, and mybook document classes. Built-in style files include:

Select one or more LaTeX packages with the package argument. Confirm that a supplied publisher style still meets the publisher's current requirements before submission.

Next steps

Try your content or define a custom style