01f2e7eb3a04c44f39a57bcf0b2c21efe8af843d
[smdp.git] / mdp.1
1 .\" This is the groff documentation source for MDP
2 .\"
3 .\" Preview with: groff -man -Tascii mdp.1
4 .\"           or: man -l mdp.1
5 .\"
6 .
7 .
8 .TH MDP 1 "2016-04-02" "User Commands"
9 .SH NAME
10 mdp \- A command-line based
11 markdown presentation tool
12 .SH SYNOPSIS
13 .B mdp
14 .RI [ OPTION ].\|.\|.\|
15 .RI [ FILE ]
16 .
17 .SH DESCRIPTION
18 .B mdp
19 is a command-line program that allows you to make elegant presentations from
20 .B markdown formatted
21 .IR FILE s.
22 .PP
23 It is as easy as write your presentation content in the text editor of your
24 preference and launch the presentation from the command-line.
25 .
26 .SH OPTIONS
27 .SS "Input Control"
28 .TP
29 .IR FILE
30 The input file from which the presentation is read. If no file is specified,
31 or if the file name is
32 .BR \- ","
33 the presentation is read from standard input.
34 .SS "Output Control"
35 .TP
36 .BR \-c ", " \-\^\-nocodebg
37 Don't change the background color of code blocks.
38 .TP
39 .BR \-e ", " \-\^\-expand
40 Enable character entity expansion (e.g. '>' becomes '>').
41 .TP
42 .BR \-s ", " \-\^\-noslidenum
43 Do not show slide number at the bottom.
44 .TP
45 .BR \-x ", " \-\^\-noslidemax
46 Show slide number, but not total number of slides.
47 .
48 .SS "Miscellaneous Options"
49 .TP
50 .BR \-d ", " \-\^\-debug
51 Enable debug messages on STDERR. Add multiple times to increases debug level.
52 .TP
53 .BR \-h ", " \-\^\-help
54 Display usage message and exit.
55 .TP
56 .BR \-v ", " \-\^\-version
57 Display version and license information.
58 .
59 .SH ENVIRONMENT VARIABLES
60 .SS "Output Control"
61 .TP
62 .BR MDP_LIST_HEAD[1-3],\ MDP_LIST_OPEN[1-3]
63 Controls the list characters of unordered lists.
64
65 The default is equivalent to:
66 .br
67 MDP_LIST_OPEN1=' |  '
68 .br
69 MDP_LIST_OPEN2=' |  '
70 .br
71 MDP_LIST_OPEN3=' |  '
72 .br
73 MDP_LIST_HEAD1=' +- '
74 .br
75 MDP_LIST_HEAD2=' +- '
76 .br
77 MDP_LIST_HEAD3=' +- '
78 .
79 .SH MARKDOWN FORMATTING
80 For a complete list of supported markups, refer the sample presentation
81 (sample.md) provided alongside
82 .BR mdp ,\|
83 or online available at
84 .IR https://github.com/visit1985/mdp .
85 .SS "Slides"
86 The input
87 .IR FILE
88 is split into multiple slides by horizontal rules. Each consisting of at least
89 3
90 .B \-\-\-
91 or
92 .B ***
93 characters on a single line.
94 .B This line must be prefixed by an completely empty line.
95 It can also contain spaces but no other characters.
96 .PP
97 If any slide is too large to fit into your current screen, an error message
98 will be displayed at the moment the presentation is launched.
99 .
100 .SS "Line-by-Line Mode"
101 .SS "Block-by-Block Mode"
102 A single
103 .BR "<br>" ", " "<BR>" " or " "^"
104 on an otherwise empty line signals
105 .B mdp
106 to stop output of the current slide (stop point) and wait for a key-press by
107 the user.
108 .PP
109 This enables the user to display bullet points or list items one by one
110 (line by line) or block by block.
111 .
112 .SS "Headers"
113 .B mdp
114 supports header lines in the format of
115 .BR @ "[DESCRIPTION] " [VALUE]
116 The first two header lines are displayed as title and author in top and
117 bottom bar.
118 .PP
119 Headers are only recognized at the top of the input
120 .IR FILE .
121 .
122 .SS "Line spanning markup"
123 Supported are headlines, code blocks, quotes and unordered lists.
124 .
125 .SS "In-line markup"
126 As well as bold text, underlined text and in-line code.
127 .
128 .SH COLOR SUPPORT
129 Most terminals are able to display 256 colors these days. But some of them
130 enable only 16 colors by default. To enjoy
131 .BR mdp "'s"
132 full capabilities, these terminals need to be signaled to enable 256 color
133 mode. This is usually done by setting the TERM environment variable.
134 .PP
135 .BR "export TERM=xterm-256color"
136 .
137 .SH KEYBOARD CONTROLS
138 .TP
139 .BR "h, j, k, l, Arrow keys, Space, Enter, Backspace, Page Up, Page Down"
140 Display next/previous slide or continue after a stop point.
141 .TP
142 .BR "g, Home"
143 Jump to first slide.
144 .TP
145 .BR "G, End"
146 Jump to last slide.
147 .TP
148 .BR "1..N"
149 Jump to
150 .BR N "th"
151 slide.
152 .TP
153 .BR "r"
154 Reload the input
155 .IR FILE .\|
156 This key is disabled if input was read from standard input.
157 .TP
158 .BR "q"
159 Exit
160 .BR mdp "."
161 .
162 .SH CUSTOMIZATION
163 .B mdp
164 can be configured by modifying config.h and recompiling.
165 .SH AUTHOR
166 Written by Michael Goehler and others, see
167 .IR https://github.com/visit1985/mdp/blob/master/AUTHORS "."
168 .SH COPYRIGHT
169 Copyright (C) 2018 Michael Goehler
170 .PP
171 This is free software; see the source for copying conditions. There is NO
172 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.