~sircmpwn/scdoc

ref: 9f74b6a0bf9794081b755274bbddd15deb6a10aa scdoc/scdoc.5.scd -rw-r--r-- 1.9 KiB
9f74b6a0Drew DeVault Parse section headings 4 years ago
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
scdoc(5)

# NAME

scdoc - syntax description for scdoc markup language

# DESCRIPTION

scdoc is a tool designed to make the process of writing man pages more
friendly. It converts scdoc files into roff macros, which can then be converted
to man pages or a number of other formats. The syntax is inspired by, but not
directly taken from, markdown. Input files *must* use the UTF-8 encoding.

# PREAMBLE

Each scdoc file must begin with the following preamble:

	*name*(_section_)

The *name* is the name of the man page you are writing, and _section_ is the
section you're writing for (see *man*(1) for information on manual sections).

# SECTION HEADERS

Each section of your man page should begin with something similar to the
following:

	# HEADER NAME

Subsection headers are also understood - use two hashes. Each header must have
an empty line on either side.

# PARAGRAPHS

Begin a new paragraph with an empty line.

# FORMATTING

Text can be made *bold* or _underlined_ with asterisks and underscores: \*bold\*
or \_underlined\_.

# INDENTATION

You may indent lines with tab characters ("\t") to indent them by 4 spaces in
the output. Indented lines may not contain headers.

# LISTS

You may start bulleted lists with dashes, like so:

```
- Item 1
- Item 2
- Item 3
```

You may also use numbered lists like so:

```
1. Item 1
2. Item 2
3. Item 3
```

# LITERAL TEXT

You may turn off scdoc formatting and output literal text with escape codes and
literal blocks. Inserting a \\ into your source will cause the subsequent symbol
to be treated as a literal and copied directly to the output. You may also make
blocks of literal syntax like so:

```
\`\`\`
_This formatting_ will *not* be interpreted by scdoc.
\`\`\`
```

These blocks will be indented one level. Note that literal text is shown
literally in the man viewer - that is, it's not a means for inserting your own
roff macros into the output.