example.scd

   1 ; This is the scdoc(5) manpage, used to test scdoc-mode.
   2
   3 scdoc(5)
   4
   5
   6 # NAME
   7
   8 scdoc - document format for writing manual pages
   9
  10 # SYNTAX
  11
  12 Input files must use the UTF-8 encoding.
  13
  14 ## PREAMBLE
  15
  16 Each scdoc file must begin with the following preamble:
  17
  18         *name*(_section_) ["left\_footer" ["center\_header"]]
  19
  20 *name* is the name of the man page you are writing, and _section_ is the section
  21 you're writing for (see *man*(1) for information on manual sections).
  22
  23 _left\_footer_ and _center\_header_ are optional arguments which set the text
  24 positioned at those locations in the generated man page, and *must* be
  25 surrounded with double quotes.
  26
  27 ## SECTION HEADERS
  28
  29 Each section of your man page should begin with something similar to the
  30 following:
  31
  32         # HEADER NAME
  33
  34 Subsection headers are also understood - use two hashes. Each header must have
  35 an empty line on either side.
  36
  37 ## PARAGRAPHS
  38
  39 Begin a new paragraph with an empty line.
  40
  41 ## LINE BREAKS
  42
  43 Insert a line break by ending a line with \+\+.
  44
  45 The result looks++
  46 like this.
  47
  48 ## FORMATTING
  49
  50 Text can be made *bold* or _underlined_ with asterisks and underscores: \*bold\*
  51 or \_underlined\_. Underscores in the_middle_of_words will be disregarded.
  52
  53 ## INDENTATION
  54
  55 You may indent lines with tab characters (*\\t*) to indent them by 4 spaces in
  56 the output. Indented lines may not contain headers.
  57
  58         The result looks something like this.
  59
  60         You may use multiple lines and most _formatting_.
  61
  62 Deindent to return to normal, or indent again to increase your indentation
  63 depth.
  64
  65 ## LISTS
  66
  67 You may start bulleted lists with dashes (-), like so:
  68
  69 ```
  70 - Item 1
  71 - Item 2
  72         - Subitem 1
  73         - Subitem 2
  74 - Item 3
  75 ```
  76
  77 The result looks like this:
  78
  79 - Item 1
  80 - Item 2
  81         - Subitem 1
  82         - Subitem 2
  83 - Item 3
  84
  85 You may also extend long entries onto another line by giving it the same indent
  86 level, plus two spaces. They will be rendered as a single list entry.
  87
  88 ```
  89 - Item 1 is pretty long so let's
  90   break it up onto two lines
  91 - Item 2 is shorter
  92         - But its children can go on
  93           for a while
  94 ```
  95
  96 - Item 1 is pretty long so let's
  97   break it up onto two lines
  98 - Item 2 is shorter
  99         - But its children can go on
 100           for a while
 101
 102 ## NUMBERED LISTS
 103
 104 Numbered lists are similar to normal lists, but begin with periods (.) instead
 105 of dashes (-), like so:
 106
 107 ```
 108 . Item 1
 109 . Item 2
 110 . Item 3,
 111   with multiple lines
 112 ```
 113
 114 . Item 1
 115 . Item 2
 116 . Item 3,
 117   with multiple lines
 118
 119 ## TABLES
 120
 121 To begin a table, add an empty line followed by any number of rows.
 122
 123 Each line of a table should start with | or : to start a new row or column
 124 respectively (or space to continue the previous cell on multiple lines),
 125 followed by [ or - or ] to align the contents to the left, center, or right,
 126 followed by a space and the contents of that cell. You may use a space instead
 127 of an alignment specifier to inherit the alignment of the same column in the
 128 previous row.
 129
 130 The first character of the first row is not limited to | and has special
 131 meaning. [ will produce a table with borders around each cell. | will produce a
 132 table with no borders. ] will produce a table with one border around the whole
 133 table.
 134
 135 To conclude your table, add an empty line after the last row.
 136
 137 ```
 138 [[ *Foo*
 139 :- _Bar_
 140 :-
 141 |  *Row 1*
 142 :  Hello
 143 :] world!
 144 |  *Row 2*
 145 :  こんにちは
 146 :  世界
 147    !
 148 ```
 149
 150 [[ *Foo*
 151 :- _Bar_
 152 :-
 153 |  *Row 1*
 154 :  Hello
 155 :] world!
 156 |  *Row 2*
 157 :  こんにちは
 158 :  世界
 159    !
 160
 161 You may also cause columns to expand to fill the available space with < (left
 162 align), = (center align), and > (right align), like so:
 163
 164 ```
 165 [[ *Normal column*
 166 :< Expanded column
 167 |  *Foo*
 168 :  Bar
 169 ```
 170
 171 [[ *Normal column*
 172 :< Expanded column
 173 |  *Foo*
 174 :  Bar
 175
 176 ## LITERAL TEXT
 177
 178 You may turn off scdoc formatting and output literal text with escape codes and
 179 literal blocks. Inserting a \\ into your source will cause the subsequent symbol
 180 to be treated as a literal and copied directly to the output. You may also make
 181 blocks of literal syntax like so:
 182
 183 ```
 184 \```
 185 _This formatting_ will *not* be interpreted by scdoc.
 186 \```
 187 ```
 188
 189 These blocks will be indented one level. Note that literal text is shown
 190 literally in the man viewer - that is, it's not a means for inserting your own
 191 roff macros into the output. Note that \\ is still interpreted within literal
 192 blocks, which for example can be useful to output \``` inside of a literal
 193 block.
 194
 195 ## COMMENTS
 196
 197 Lines beginning with ; and a space are ignored.
 198
 199 ```
 200 ; This is a comment
 201 ```
 202
 203 # CONVENTIONS
 204
 205 By convention, all scdoc documents should be hard wrapped at 80 columns.
 206
 207 # SEE ALSO
 208
 209 *scdoc*(1)
 210
 211 # AUTHORS
 212
 213 Maintained by Drew DeVault <sir@cmpwn.com>. Up-to-date sources can be found at
 214 https://git.sr.ht/~sircmpwn/scdoc and bugs/patches can be submitted by email to
 215 ~sircmpwn/public-inbox@lists.sr.ht.