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
183
184
185
186
187
188
189
190
191
192
193
194
195
|
************************************************************************
* Official mandoc TODO.
* $Id: TODO,v 1.42 2010/08/20 22:51:29 schwarze Exp $
************************************************************************
************************************************************************
* 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.
- look at bsd.lv tbl(1)
from kristaps@ Fri, 11 Sep 2009 17:10:53 +0200
also look at the mail from Thomas Klausner wiz at NetBSD
on Wed, 2 Jun 2010 11:01:29 +0200
joerg@ has patches for this somewhere...
- 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
- 'br\} doesn't correctly close scope.
Noted by joerg@, 28/7/2010.
************************************************************************
* 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
- %A doesn't put an "and" before the final author name.
************************************************************************
* 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)
- .It ${name Ns [ selector ] Ns }
should be "${name[selector]}" not "${name [selector]}"
This is parsed as
text("${name") text("[") Ns() text(selector)...
Opening punctuation should not fall out of .Ns.
see for example OpenBSD csh(1)
- .%A should append the last author with " and " (if there are two)
or ", and " (if there are more), not ", "
see for example OpenBSD csh(1)
- In .Bl -bullet, the groff bullet is "+\b+\bo\bo", the mandoc bullet
is just "o\bo".
see for example OpenBSD ksh(1)
- .No text No ) is "text )", not "text)"
see the terrible example
case word in [[(] pattern [| pattern] ... ) list ;; ] ... esac
in OpenBSD ksh(1)
- .Sm should *not* produce as a blank line in .Bd -literal
see for example "Brace expansion" in 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).
- In .Bd -unfilled, .Pp should produce one blank line, not two;
see the ccd.conf 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).
- When .%T is used outside an .Rs context and with a trailing comma,
there is no point in rendering two commata,
see the first paragraph of the DESCRIPTION in OpenBSD mount_nfs(8).
- When .%T is used outside an .Rs context and without a trailing comma,
no comma should be rendered at all,
see the first paragraph of the DESCRIPTION in OpenBSD exports(5).
- Bogus .Pp before .Bl should not cause a double blank line,
see "The route utility provides the following simple commands:"
in OpenBSD route(8).
************************************************************************
* 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
************************************************************************
- rendering frontend code can calculate widths only for plain strings,
not for strings containing escape sequences. For example, this
hinders calculation of the indent required for .Nm \&[ in text(1).
comments from kristaps@ Wed, 21 Jul 2010 23:26:08 +0200
- another example of the same problem:
.Bl -tag -width "\eD{format}XX" -compact
in OpenBSD ksh(1) gives the wrong width
because "\e" is one character in groff, two in mandoc
- Now that `ds' is minimally supported, we can get rid of some
predefined strings. \*(C+ has already been thrown out. Track these
down and whack them. Look in e.g. gcc.1 for the top-level `ds'
invocations. These are reproduced across most crappy GNU manuals.
|
