]> git.cameronkatri.com Git - mandoc.git/blob - TODO
mini-bug at eol after .Bl -column .It
[mandoc.git] / TODO
1 ************************************************************************
2 * Official mandoc TODO.
3 * $Id: TODO,v 1.102 2011/04/16 23:00:45 schwarze Exp $
4 ************************************************************************
5
6 ************************************************************************
7 * parser bugs
8 ************************************************************************
9
10 - .TP before .SH is still FATAL in man(7)
11 reported by brad@ Sat, 15 Jan 2011 15:54:54 -0500
12
13 - the roff parser doesn't tolerate additional characters between
14 a macro and the \} terminating a conditional block, e.g.
15 .if n \{
16 .br \}
17 reported by ulrich spoerlein Tue, 19 Oct 2010 20:39:50 +0200
18
19 ************************************************************************
20 * formatter bugs
21 ************************************************************************
22
23 - tbl(7): Horizontal and vertical lines are formatted badly:
24 With the box option, there is too much white space at the end of cells.
25 Horizontal lines from "=" lines are a bit too long.
26 yuri dot pankov at gmail dot com Thu, 14 Apr 2011 05:45:26 +0400
27
28 ************************************************************************
29 * missing features
30 ************************************************************************
31
32 --- missing roff features ----------------------------------------------
33
34 - .ad (adjust margins)
35 .ad l -- adjust left margin only (flush left)
36 .ad r -- adjust right margin only (flush right)
37 .ad c -- center text on line
38 .ad b -- adjust both margins (alias: .ad n)
39 .na -- temporarily disable adjustment without changing the mode
40 .ad -- re-enable adjustment without changing the mode
41 Adjustment mode is ignored while in no-fill mode (.nf).
42
43 - .it (line traps) occur in mysql(1), yasm_arch(7)
44 generated by DocBook XSL Stylesheets v1.71.1 <http://docbook.sf.net/>
45 reported by brad@ Sat, 15 Jan 2011 15:48:18 -0500
46
47 - .ns (no-space mode) occurs in xine-config(1)
48 reported by brad@ Sat, 15 Jan 2011 15:45:23 -0500
49
50 - xloadimage(1) wants .ti (temporary indent), rep by naddy@
51
52 - .ta (tab settings) occurs in ircbug(1) and probably gnats(1)
53 reported by brad@ Sat, 15 Jan 2011 15:50:51 -0500
54
55 - pod2man expects `tr' to be implemented for \*(-- to work
56
57 - \c (interrupted text) occurs in chat(8)
58
59 - \f(CW (constant width font) occurs in rsyncd.conf(5).
60 I think we should treat unknown/unavailable fonts as \fR
61 such that switching back with \fP works correctly -
62 and doesn't revert the _previous_ \fP.
63
64 --- missing mdoc features ----------------------------------------------
65
66 - fix bad block nesting involving multiple identical explicit blocks
67 see the OpenBSD mdoc_macro.c 1.47 commit message
68
69 - .Bl -column .Xo support is missing
70 ultimate goal:
71 restore .Xr and .Dv to
72 lib/libc/compat-43/sigvec.3
73 lib/libc/gen/signal.3
74 lib/libc/sys/sigaction.2
75
76 - edge case: decide how to deal with blk_full bad nesting, e.g.
77 .Sh .Nm .Bk .Nm .Ek .Sh found by jmc@ in ssh-keygen(1)
78 from jmc@ Wed, 14 Jul 2010 18:10:32 +0100
79
80 - \\ is now implemented correctly
81 * when defining strings and macros using .ds and .de
82 * when parsing roff(7) and man(7) macro arguments
83 It does not yet work in mdoc(7) macro arguments
84 because libmdoc does not yet use mandoc_getarg().
85 Also check what happens in plain text, it must be identical to \e.
86
87 - .Bd -filled should not be the same as .Bd -ragged, but align both
88 the left and right margin. In groff, it is implemented in terms
89 of .ad b, which we don't have either. Found in cksum(1).
90
91 - implement blank `Bl -column', such as
92 .Bl -column
93 .It foo Ta bar
94 .El
95
96 - explicitly disallow nested `Bl -column', which would clobber internal
97 flags defined for struct mdoc_macro
98
99 - In .Bl -column .It, the end of the line probably has to be regarded
100 as an implicit .Ta, if there could be one, see the following mildly
101 ugly code from login.conf(5):
102 .Bl -column minpasswordlen program xetcxmotd
103 .It path Ta path Ta value of Dv _PATH_DEFPATH
104 .br
105 Default search path.
106 reported by Michal Mazurek <akfaew at jasminek dot net>
107 via jmc@ Thu, 7 Apr 2011 16:00:53 +0059
108
109 - inside `.Bl -column' phrases, punctuation is handled like normal
110 text, e.g. `.Bl -column .It Fl x . Ta ...' should give "-x -."
111
112 - inside `.Bl -column' phrases, TERMP_IGNDELIM handling by `Pf'
113 is not safe, e.g. `.Bl -column .It Pf a b .' gives "ab."
114 but should give "ab ."
115
116 - set a meaningful default if no `Bl' list type is assigned
117
118 - have a blank `It' head for `Bl -tag' not puke
119
120 - prohibit `Nm' from having non-text HEAD children
121 (e.g., NetBSD mDNSShared/dns-sd.1)
122 (mdoc_html.c and mdoc_term.c `Nm' handlers can be slightly simplified)
123
124 --- missing man features -----------------------------------------------
125
126 - .RS/.RE can be nested, see e.g. the x11/fluxbox manuals
127 noticed by dcoppa@ Wed, Apr 13, 2011 at 04:58:14PM +0200:
128
129 - groff an-ext.tmac macros (.UR, .UE) occur in xine(5)
130 reported by brad@ Sat, 15 Jan 2011 15:45:23 -0500
131
132 --- missing tbl features -----------------------------------------------
133
134 - implement basic non-parametric .de to support e.g. sox(1)
135 reported by naddy@ Sat, 16 Oct 2010 23:51:57 +0200
136 *** sox(1) still doesn't work, tbl(1) errors need investigation
137
138 --- missing misc features ----------------------------------------------
139
140 - clean up escape sequence handling, creating three classes:
141 (1) fully implemented, or parsed and ignored without loss of content
142 (2) unimplemented, potentially causing loss of content
143 or serious mangling of formatting (e.g. \n) -> ERROR
144 see textproc/mgdiff(1) for nice examples
145 (3) undefined, just output the character -> perhaps WARNING
146
147 - The \t escape sequence is the same as a literal tab, see for example
148 the ASCII table in hexdump(1) where
149 .Bl -column \&000_nu \&001_so \&002_st \&003_et \&004_eo
150 .It \&000\ nul\t001\ soh\t002\ stx\t003\ etx\t004\ eot\t005\ enq
151 produces
152 000 nul 001 soh 002 stx 003 etx 004 eot 005 enq
153 and the example in oldrdist(1)
154
155 - look at pages generated from reStructeredText, e.g. devel/mercurial hg(1)
156 These are a weird mixture of man(7) and custom autogenerated low-level
157 roff stuff. Figure out to what extent we can cope.
158 For details, see http://docutils.sourceforge.net/rst.html
159 noted by stsp@ Sat, 24 Apr 2010 09:17:55 +0200
160 reminded by nicm@ Mon, 3 May 2010 09:52:41 +0100
161
162 - check compatibility with Plan9:
163 http://swtch.com/usr/local/plan9/tmac/tmac.an
164 http://swtch.com/plan9port/man/man7/man.html
165 "Anthony J. Bentley" <anthonyjbentley@gmail.com> 28 Dec 2010 21:58:40 -0700
166
167 ************************************************************************
168 * formatting issues: ugly output
169 ************************************************************************
170
171 - a column list with blank `Ta' cells triggers a spurrious
172 start-with-whitespace printing of a newline
173
174 - double quotes inside double quotes are escaped by doubling them
175 implement this in mdoc(7), too
176 so far, we only have it in roff(7) and man(7)
177 reminded by millert@ Thu, 09 Dec 2010 17:29:52 -0500
178
179 - perl(1) SYNOPSIS looks bad; reported by deraadt@
180 1) man(7) seems to need SYNOPSIS .Nm blocks, too
181
182 - In .Bl -column,
183 .It Em Authentication<tab>Key Length
184 ought to render "Key Length" with emphasis, too,
185 see OpenBSD iked.conf(5).
186
187 - empty phrases in .Bl column produce too few blanks
188 try e.g. .Bl -column It Ta Ta
189 reported by millert Fri, 02 Apr 2010 16:13:46 -0400
190
191 - .%T can have trailing punctuation. Currently, it puts the trailing
192 punctuation into a trailing MDOC_TEXT element inside its own scope.
193 That element should rather be outside its scope, such that the
194 punctuation does not get underlines. This is not trivial to
195 implement because .%T then needs some features of in_line_eoln() -
196 slurp all arguments into one single text element - and one feature
197 of in_line() - put trailing punctuation out of scope.
198 Found in mount_nfs(8) and exports(5), search for "Appendix".
199
200 - in enclosures, mandoc sometimes fancies a bogus end of sentence
201 reminded by jmc@ Thu, 23 Sep 2010 18:13:39 +0059
202
203 ************************************************************************
204 * formatting issues: gratuitious differences
205 ************************************************************************
206
207 - .Rv (and probably .Ex) print different text if an `Nm' has been named
208 or not (run a manual without `Nm blah' to see this). I'm not sure
209 that this exists in the wild, but it's still an error.
210
211 - In .Bl -bullet, the groff bullet is "+\b+\bo\bo", the mandoc bullet
212 is just "o\bo".
213 see for example OpenBSD ksh(1)
214
215 - The characters "|" and "\*(Ba" should never be bold,
216 not even in the middle of a word, e.g. ".Cm b\*(Bac" in
217 "mknod [-m mode] name b|c major minor"
218 in OpenBSD ksh(1)
219
220 - A bogus .Pp between two .It must not produce a double blank line,
221 see between -R and -r in OpenBSD rm(1), before "update" in mount(8),
222 or in DIAGNOSTICS in init(8), or before "is always true" in ksh(1).
223 The same happens with .Pp just before .El, see bgpd.conf(5).
224 Also have `It' complain if `Pp' is invoked at certain times (not
225 -compact?).
226
227 - If the *first* line after .It is .Pp, break the line right after
228 the tag, do not pad with space characters before breaking.
229 See the description of the a, c, and i commands in sed(1).
230
231 - If the first line after .It is .D1, do not assert a blank line
232 in between, see for example tmux(1).
233 reported by nicm@ 13 Jan 2011 00:18:57 +0000
234
235 - .Nx 1.0a
236 should be "NetBSD 1.0A", not "NetBSD 1.0a",
237 see OpenBSD ccdconfig(8).
238
239 - In .Bl -tag, if a tag exceeds the right margin and must be continued
240 on the next line, it must be indented by -width, not width+1;
241 see "rule block|pass" in OpenBSD ifconfig(8).
242
243 - When the -width string contains macros, the macros must be rendered
244 before measuring the width, for example
245 .Bl -tag -width ".Dv message"
246 in magic(5), located in src/usr.bin/file, is the same
247 as -width 7n, not -width 11n.
248
249 - The \& zero-width character counts as output.
250 That is, when it is alone on a line between two .Pp,
251 we want three blank lines, not two as in mandoc.
252
253 - When .Fn arguments exceed one output line, all but the first
254 should be indented, see e.g. rpc(3);
255 reported by jmc@ on discuss@ Fri, 29 Oct 2010 13:48:33 +0100
256
257 - .Ns should work when called at the end of an input line, see
258 the following code in vi(1):
259 .It Xo
260 .Op Ar line
261 .Cm a Ns Op Cm ppend Ns
262 .Op Cm !\&
263 .Xc
264 The input text is appended after the specified line.
265
266 - Header lines of excessive length:
267 Port OpenBSD man_term.c rev. 1.25 to mdoc_term.c
268 and document it in mdoc(7) and man(7) COMPATIBILITY
269 found while talking to Chris Bennett
270
271 - In man(7), the sequence
272 .HP
273 one line of regular text
274 .SH
275 should not produce two blank lines before the .SH,
276 see for example named-checkconf(8).
277
278 - In man(7), the sequence
279 regular text
280 .RS
281 .IP
282 should have a blank line between the text and the beginning of the
283 indented paragraph, see for example sudo(1).
284
285 - In man(7), the sequence
286 .SH HEADER
287 <blank line>
288 .PP
289 regular text
290 should not produce any blank lines between the header and the text,
291 see for example rsync(1).
292 Reported by naddy@ Mon, 28 Mar 2011 20:45:42 +0200
293
294 - In man(7), the sequence
295 regular text
296 .PP
297 .RS
298 indented text
299 should produce one blank line between the regular and indented texts,
300 see for example rsync(1), and
301 .RE
302 <blank line>
303 .PP
304 .RS
305 should produce two,not one blank lines.
306 Reported by naddy@ Mon, 28 Mar 2011 20:45:42 +0200
307
308 - In man(7), the sequence
309 regular text
310 .IP
311 .IP "tag"
312 indented text
313 should produce one, not four blank lines between the regular text
314 and the tag, see for example rsync(1).
315 Likewise,
316 regular text
317 .IP
318 indented text
319 should produce one, not two blank lines in between, and
320 regular text
321 .IP
322 .RS
323 .IP tag
324 indented text
325 should produce one, not three blank lines.
326 Reported by naddy@ Mon, 28 Mar 2011 20:45:42 +0200
327
328 - At least sometimes, .sp is ignored right after .SH; see named.conf(5).
329
330 - trailing whitespace must be ignored even when followed by a font escape,
331 see for example
332 makes
333 \fBdig \fR
334 operate in batch mode
335 in dig(1).
336
337 ************************************************************************
338 * error reporting issues
339 ************************************************************************
340
341 ************************************************************************
342 * performance issues
343 ************************************************************************
344
345 Several areas can be cleaned up to make mandoc even faster. These are
346
347 - improve hashing mechanism for macros (quite important: performance)
348
349 - improve hashing mechanism for characters (not as important)
350
351 - the PDF file is HUGE: this can be reduced by using relative offsets
352
353 ************************************************************************
354 * structural issues
355 ************************************************************************
356
357 - Find better ways to prevent endless loops
358 in roff(7) macro and string expansion.
359
360 - Finish cleanup of date handling.
361 Decide which formats should be recognized where.
362 Update both mdoc(7) and man(7) documentation.
363 Triggered by Tim van der Molen Tue, 22 Feb 2011 20:30:45 +0100