scdoc

Generate man pages from a scdoc (.scd) file

$ scdoc < [path/to/file.scd] > [path/to/file.1]

$ scdoc < [path/to/file.scd] | [less]

scdoc [OPTIONS] [INPUT_FILE]

Examples:
scdoc input.scd > output.man
scdoc -t html input.scd > output.html
scdoc -o output.man input.scd

-h
    Displays a brief help message explaining the command's usage and options, then exits.

-v
    Prints the version information of the scdoc utility to standard output, then exits.

-t <type>
    Specifies the desired output format. Valid types include man (for roff/man page format, which is the default), html, and plain (for plain text).

-o <output_file>
    Redirects the generated output to the specified <output_file> instead of standard output.

-i <input_file>
    Specifies the input file containing the scdoc markup. If this option is omitted, scdoc reads its input from standard input (stdin).

INPUT_FILE
    The path to the scdoc markup file to be processed. This is typically used as a positional argument if the -i flag is not used.

The scdoc command is a minimalist and efficient tool designed for generating documentation in various formats, primarily manual pages (man pages), HTML, and plain text. It processes a simplified markup language, also called scdoc, allowing users to write documentation using a straightforward, human-readable syntax. Unlike more complex document formatting systems like groff or DocBook, scdoc focuses on ease of use and a shallow learning curve, making it ideal for projects that require quick and simple man page generation without extensive dependencies. Its markup supports essential formatting features such as headers, lists, bold and italic text, code blocks, and links, translating them into standard output formats. This utility is often favored in minimalist development environments for its small footprint and direct approach to documentation.

While scdoc excels in simplicity and ease of use, its feature set is intentionally minimalist compared to more comprehensive document formatting systems like groff or DocBook. This means it might lack advanced layout control, complex macro capabilities, or intricate styling options. Users should be aware that the scdoc markup is specific to this tool, requiring authors to learn its particular syntax.

The scdoc markup language is designed to be intuitive and easy to write. It uses a line-based syntax where specific characters at the beginning of a line denote structural elements, and inline formatting uses simple delimiters.

Key features include:
.NAME: Defines section headers (e.g., .NAME, .SYNOPSIS, .DESCRIPTION, .OPTIONS, .AUTHORS).
= Headings =: Creates top-level headings.
== Subheadings ==: Creates sub-level headings.
_word_: Renders text in italics.
*word*: Renders text in bold.
`code`: Renders text as code or verbatim.
> List Item: Creates bulleted list items.
$ command example: Denotes a command line example or code block.
This simple syntax allows for rapid creation of structured documentation.

scdoc emerged as a modern, lightweight alternative to traditional and often more complex document preparation systems. It aligns with the philosophy of minimalist tools, prioritizing a small codebase, minimal dependencies, and a straightforward workflow. While not officially part of the suckless.org suite, it shares a similar design ethos, gaining popularity among developers who prefer simple text-based markup and command-line utilities for their documentation needs. Its development focused on providing a quick and easy way to generate professional-looking man pages and other documentation formats without the steep learning curve associated with older systems.

man(1), groff(1), pandoc(1), mandoc(1), roff(7)