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
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
|
************************************************************************
* Official mandoc TODO.
* $Id$
************************************************************************
************************************************************************
* parser bugs
************************************************************************
- the roff parser doesn't tolerate additional characters between
a macro and the \} terminating a conditional block, e.g.
.if n \{
.br \}
reported by ulrich spoerlein Tue, 19 Oct 2010 20:39:50 +0200
************************************************************************
* missing features
************************************************************************
- explicit blocks with missing end macro should be implicitely closed
at the end of the enclosing block, e.g. .Bl It (El) Sh
reminded by stsp@ in net/pptp pptp.8 Fri, 23 Apr 2010 20:32:39 +0200
- fix bad block nesting involving multiple identical explicit blocks
see the OpenBSD mdoc_macro.c 1.47 commit message
- .Bl -column .Xo support is missing
ultimate goal:
restore .Xr and .Dv to
lib/libc/compat-43/sigvec.3
lib/libc/gen/signal.3
lib/libc/sys/sigaction.2
- edge case: decide how to deal with blk_full bad nesting, e.g.
.Sh .Nm .Bk .Nm .Ek .Sh found by jmc@ in ssh-keygen(1)
from jmc@ Wed, 14 Jul 2010 18:10:32 +0100
- auto-Bk in the SYNOPSIS
patch from kristaps@ Fri, 16 Jul 2010 14:51:24 +0200
to be revisited after OpenBSD 4.8 tree unlock
- implement \\
in plain text, identical to \e
as a macro argument, identical to \ i.e. escaping the next character
We do not have macro definitions yet; if we implement them,
\\ must behave in a macro def like in a macro argument,
and when using the macro, it must expand yet again.
- implement basic non-parametric .de to support e.g. sox(1)
.de SP
.if t .sp .5
.if n .sp
..
.de EX
.SP
.nf
.ft CW
..
.de EE
.ft R
.SP
.fi
..
reported by naddy@ Sat, 16 Oct 2010 23:51:57 +0200
- clean up escape sequence handling, creating three classes:
(1) fully implemented, or parsed and ignored without loss of content
(2) unimplemented, potentially causing loss of content
or serious mangling of formatting (e.g. \n) -> ERROR
see textproc/mgdiff(1) for nice examples
(3) undefined, just output the character -> perhaps WARNING
- port OpenBSD tbl integration bsd.lv, probably cleaning it up
- look at pages generated from reStructeredText, e.g. devel/mercurial hg(1)
These are a weird mixture of man(7) and custom autogenerated low-level
roff stuff. Figure out to what extent we can cope.
noted by stsp@ Sat, 24 Apr 2010 09:17:55 +0200
reminded by nicm@ Mon, 3 May 2010 09:52:41 +0100
- implement blank `Bl -column', such as
.Bl -column
.It foo Ta bar
.El
- explicitly disallow nested `Bl -column', which would clobber internal
flags defined for struct mdoc_macro
- inside `.Bl -column' phrases, punctuation is handled like normal
text, e.g. `.Bl -column .It Fl x . Ta ...' should give "-x -."
- inside `.Bl -column' phrases, TERMP_IGNDELIM handling by `Pf'
is not safe, e.g. `.Bl -column .It Pf a b .' gives "ab."
but should give "ab ."
- set a meaningful default if no `Bl' list type is assigned
- have a blank `It' head for `Bl -tag' not puke
- prohibit `Nm' from having non-text HEAD children
(e.g., NetBSD mDNSShared/dns-sd.1)
(mdoc_html.c and mdoc_term.c `Nm' handlers can be slightly simplified)
- allow `Qq', `Dq', `Sq', `Aq', `Bq' to have 0 arguments
noted by Alex Kozlov 08/06/10 23:05
- Have `Sh', `It', `Ss' and others complain if `Pp' is invoked prior to
close (in the post validation) or prior to open (pre). This noted by
jmc@ a thousand years ago.
************************************************************************
* formatting issues: ugly output
************************************************************************
- perl(1) SYNOPSIS looks bad; reported by deraadt@
1) man(7) seems to need SYNOPSIS .Nm blocks, too
- In .Bl -column,
.It Em Authentication<tab>Key Length
ought to render "Key Length" with emphasis, too,
see OpenBSD iked.conf(5).
- empty phrases in .Bl column produce too few blanks
try e.g. .Bl -column It Ta Ta
reported by millert Fri, 02 Apr 2010 16:13:46 -0400
- in enclosures, mandoc sometimes fancies a bogus end of sentence
reminded by jmc@ Thu, 23 Sep 2010 18:13:39 +0059
************************************************************************
* formatting issues: gratuitious differences
************************************************************************
- .%T should be quoted, not underlined, when .%J is also present,
to better distinguish the contents of .%T and .%J,
see for example OpenBSD cat(1)
- In .Bl -bullet, the groff bullet is "+\b+\bo\bo", the mandoc bullet
is just "o\bo".
see for example OpenBSD ksh(1)
- The characters "|" and "\*(Ba" should never be bold,
not even in the middle of a word, e.g. ".Cm b\*(Bac" in
"mknod [-m mode] name b|c major minor"
in OpenBSD ksh(1)
- A bogus .Pp between two .It must not produce a double blank line,
see between -R and -r in OpenBSD rm(1), before "update" in mount(8),
or in DIAGNOSTICS in init(8).
- .Bd -literal and .Bd -unfilled are *not* identical.
In -literal, tabs are 8 spaces.
In -unfilled, tabs are 5 spaces, just like in -filled and -ragged.
See the CCDF_* display in OpenBSD ccdconfig(8).
- .Nx 1.0a
should be "NetBSD 1.0A", not "NetBSD 1.0a",
see OpenBSD ccdconfig(8).
- In .Bl -tag, if a tag exceeds the right margin and must be continued
on the next line, it must be indented by -width, not width+1;
see "rule block|pass" in OpenBSD ifconfig(8).
- The \& zero-width character counts as output.
That is, when it is alone on a line between two .Pp,
we want three blank lines, not two as in mandoc.
************************************************************************
* performance issues
************************************************************************
Several areas can be cleaned up to make mandoc even faster. These are
- improve hashing mechanism for macros (quite important: performance)
- improve hashing mechanism for characters (not as important)
- the PDF file is HUGE: this can be reduced by using relative offsets
************************************************************************
* structural issues
************************************************************************
|
