Browse Source

Add "Writing mdoc"

June 2 months ago
parent
commit
23ebf94ea8
Signed by: Curtis McEnroe <june@causal.agency> GPG Key ID: CEA2F97ADCFCD77C
2 changed files with 139 additions and 0 deletions
  1. 138
    0
      002-writing-mdoc.7
  2. 1
    0
      Makefile

+ 138
- 0
002-writing-mdoc.7 View File

@@ -0,0 +1,138 @@
1
+.Dd September 27, 2018
2
+.Dt WRITING-MDOC 7
3
+.Os "Causal Agency"
4
+.
5
+.Sh NAME
6
+.Nm Writing mdoc
7
+.Nd semantic markup
8
+.
9
+.Sh DESCRIPTION
10
+I recently learned how to write man pages
11
+so that I could document
12
+a bunch of little programs I've written.
13
+Modern man pages are written in
14
+.Xr mdoc 7 ,
15
+whose documentation is also available from
16
+.Lk http://mandoc.bsd.lv .
17
+.
18
+.Pp
19
+.Xr mdoc 7
20
+differs from many other markup languages
21
+by providing
22
+.Dq semantic markup
23
+rather than just
24
+.Dq physical markup.
25
+What this means is that
26
+the markup indicates what something is,
27
+not how to format it.
28
+For example,
29
+the
30
+.Ql \&Ar
31
+macro is used to indicate
32
+command-line arguments
33
+rather than one of the macros
34
+for bold, italic or underline.
35
+This frees each author of having to choose
36
+and enables consistent presentation
37
+across different man pages.
38
+.
39
+.Pp
40
+Another advantage of semantic markup
41
+is that information can be extracted from it.
42
+For example,
43
+.Xr makewhatis 8
44
+can easily extract the name and short description
45
+from each man page
46
+thanks to the
47
+.Ql \&Nm
48
+and
49
+.Ql \&Nd
50
+macros.
51
+I use the same information
52
+to generate an Atom feed for these documents,
53
+though in admittedly a much less robust way than
54
+.Xr mandoc 1 .
55
+.
56
+.Pp
57
+When it comes to actually writing
58
+.Xr mdoc 7 ,
59
+it can take some getting used to.
60
+The language is of
61
+.Xr roff 7
62
+lineage
63
+so its syntax is very particular.
64
+Macros cannot appear inline,
65
+but must start on new lines
66
+beginning with
67
+.Ql \&. .
68
+Sentences should likewise
69
+always start on a new line.
70
+Since I'm in the habit of writing with
71
+semantic line breaks,
72
+I actually find these requirements
73
+fit in well.
74
+.
75
+.Pp
76
+The more frustrating syntax limitation to me
77
+is the rule against empty lines.
78
+Without them,
79
+it can be quite difficult to edit a lengthy document.
80
+Thankfully,
81
+lines with only a
82
+.Ql \&.
83
+on them are allowed,
84
+but this still causes visual noise.
85
+To alleviate that,
86
+I have a
87
+.Xr vim 1
88
+syntax file for
89
+.Xr mdoc 7
90
+which conceals the lone dots:
91
+.
92
+.Bd -literal -offset indent
93
+if exists("b:current_syntax")
94
+	finish
95
+endif
96
+
97
+runtime! syntax/nroff.vim
98
+unlet! b:current_syntax
99
+
100
+setlocal sections+=ShSs
101
+syntax match mdocBlank /^\\.$/ conceal
102
+setlocal conceallevel=2
103
+
104
+let b:current_syntax = "mdoc"
105
+.Ed
106
+.
107
+.Pp
108
+It also adds the
109
+.Xr mdoc 7
110
+section header and subsection header macros to the
111
+.Cm sections
112
+option to make
113
+.Xr vim 1 Ap s
114
+.Ic {
115
+and
116
+.Ic }
117
+motions
118
+aware of them.
119
+.
120
+.Pp
121
+With that,
122
+I've found writing man pages pleasant and rewarding.
123
+I've started writing other documents with
124
+.Xr mdoc 7
125
+as well,
126
+as you can see here.
127
+.
128
+.Sh SEE ALSO
129
+.Lk http://rhodesmill.org/brandon/2012/one-sentence-per-line/ "Semantic Linefeeds"
130
+.
131
+.Sh AUTHORS
132
+.An June Aq Mt june@causal.agency
133
+.
134
+.Pp
135
+This document is produced from
136
+.Xr mdoc 7
137
+source available from
138
+.Lk https://code.causal.agency/june/text.causal.agency "Code Toilet"

+ 1
- 0
Makefile View File

@@ -1,6 +1,7 @@
1 1
 WEBROOT = /usr/local/www/text.causal.agency
2 2
 
3 3
 TXTS += 001-make.txt
4
+TXTS += 002-writing-mdoc.txt
4 5
 
5 6
 all: $(TXTS)
6 7
 

Loading…
Cancel
Save