]> git.cameronkatri.com Git - mandoc.git/blob - TODO
espie@ suggests using SQL views
[mandoc.git] / TODO
1 ************************************************************************
2 * Official mandoc TODO.
3 * $Id: TODO,v 1.170 2014/04/23 16:37:43 schwarze Exp $
4 ************************************************************************
5
6 ************************************************************************
7 * crashes
8 ************************************************************************
9
10 - The abort() in bufcat(), html.c, can be triggered via buffmt_includes()
11 by running -Thtml -Oincludes on a file containing a long .In argument.
12 Fixing this will probably require reworking the whole bufcat() concept.
13
14 ************************************************************************
15 * missing features
16 ************************************************************************
17
18 --- missing roff features ----------------------------------------------
19
20 - .ad (adjust margins)
21 .ad l -- adjust left margin only (flush left)
22 .ad r -- adjust right margin only (flush right)
23 .ad c -- center text on line
24 .ad b -- adjust both margins (alias: .ad n)
25 .na -- temporarily disable adjustment without changing the mode
26 .ad -- re-enable adjustment without changing the mode
27 Adjustment mode is ignored while in no-fill mode (.nf).
28
29 - .fc (field control)
30 found by naddy@ in xloadimage(1)
31
32 - .nr third argument (auto-increment step size, requires \n+)
33 found by bentley@ in sbcl(1) Mon, 9 Dec 2013 18:36:57 -0700
34
35 - .ns (no-space mode) occurs in xine-config(1)
36 reported by brad@ Sat, 15 Jan 2011 15:45:23 -0500
37
38 - .ta (tab settings) occurs in ircbug(1) and probably gnats(1)
39 reported by brad@ Sat, 15 Jan 2011 15:50:51 -0500
40 also Tcl_NewStringObj(3) via wiz@ Wed, 5 Mar 2014 22:27:43 +0100
41
42 - .ti (temporary indent)
43 found by naddy@ in xloadimage(1)
44 found by bentley@ in nmh(1) Mon, 23 Apr 2012 13:38:28 -0600
45
46 - .while and .shift
47 found by jca@ in ratpoison(1) Sun, 30 Jun 2013 12:01:09 +0200
48
49 - \c (interrupted text) should prevent the line break
50 even inside .Bd literal; that occurs in chat(8)
51 also found in cclive(1) - DocBook output
52
53 - \h horizontal move
54 found in cclive(1) DocBook output
55 Anthony J. Bentley on discuss@ Sat, 21 Sep 2013 22:29:34 -0600
56
57 - \n+ and \n- numerical register increment and decrement
58 found by bentley@ in sbcl(1) Mon, 9 Dec 2013 18:36:57 -0700
59
60 - \w'' width measurements
61 would not be very useful without an expression parser, see below
62 needed for Tcl_NewStringObj(3) via wiz@ Wed, 5 Mar 2014 22:27:43 +0100
63
64 - using undefined strings or macros defines them to be empty
65 wl@ Mon, 14 Nov 2011 14:37:01 +0000
66
67 - general expression parser, including arithmetics
68 to be used at least for .if/.ie and .nr and maybe at other places
69 could use J.T.Conklin's PD code in bin/expr/expr.c for inspiration
70 needed for Tcl_NewStringObj(3) via wiz@ Wed, 5 Mar 2014 22:27:43 +0100
71
72 --- missing mdoc features ----------------------------------------------
73
74 - fix bad block nesting involving multiple identical explicit blocks
75 see the OpenBSD mdoc_macro.c 1.47 commit message
76
77 - .Bl -column .Xo support is missing
78 ultimate goal:
79 restore .Xr and .Dv to
80 lib/libc/compat-43/sigvec.3
81 lib/libc/gen/signal.3
82 lib/libc/sys/sigaction.2
83
84 - edge case: decide how to deal with blk_full bad nesting, e.g.
85 .Sh .Nm .Bk .Nm .Ek .Sh found by jmc@ in ssh-keygen(1)
86 from jmc@ Wed, 14 Jul 2010 18:10:32 +0100
87
88 - \\ is now implemented correctly
89 * when defining strings and macros using .ds and .de
90 * when parsing roff(7) and man(7) macro arguments
91 It does not yet work in mdoc(7) macro arguments
92 because libmdoc does not yet use mandoc_getarg().
93 Also check what happens in plain text, it must be identical to \e.
94
95 - .Bd -filled should not be the same as .Bd -ragged, but align both
96 the left and right margin. In groff, it is implemented in terms
97 of .ad b, which we don't have either. Found in cksum(1).
98
99 - implement blank `Bl -column', such as
100 .Bl -column
101 .It foo Ta bar
102 .El
103
104 - explicitly disallow nested `Bl -column', which would clobber internal
105 flags defined for struct mdoc_macro
106
107 - In .Bl -column .It, the end of the line probably has to be regarded
108 as an implicit .Ta, if there could be one, see the following mildly
109 ugly code from login.conf(5):
110 .Bl -column minpasswordlen program xetcxmotd
111 .It path Ta path Ta value of Dv _PATH_DEFPATH
112 .br
113 Default search path.
114 reported by Michal Mazurek <akfaew at jasminek dot net>
115 via jmc@ Thu, 7 Apr 2011 16:00:53 +0059
116
117 - inside `.Bl -column' phrases, punctuation is handled like normal
118 text, e.g. `.Bl -column .It Fl x . Ta ...' should give "-x -."
119
120 - inside `.Bl -column' phrases, TERMP_IGNDELIM handling by `Pf'
121 is not safe, e.g. `.Bl -column .It Pf a b .' gives "ab."
122 but should give "ab ."
123
124 - set a meaningful default if no `Bl' list type is assigned
125
126 - have a blank `It' head for `Bl -tag' not puke
127
128 - prohibit `Nm' from having non-text HEAD children
129 (e.g., NetBSD mDNSShared/dns-sd.1)
130 (mdoc_html.c and mdoc_term.c `Nm' handlers can be slightly simplified)
131
132 - When there is free text in the SYNOPSIS and that free text contains
133 the .Nm macro, groff somehow understands to treat the .Nm as an in-line
134 macro, while mandoc treats it as a block macro and breaks the line.
135 No idea how the logic for distinguishing in-line and block instances
136 should be, needs investigation.
137 uqs@ Thu, 2 Jun 2011 11:03:51 +0200
138 uqs@ Thu, 2 Jun 2011 11:33:35 +0200
139
140 --- missing man features -----------------------------------------------
141
142 - -T[x]html doesn't stipulate non-collapsing spaces in literal mode
143
144 --- missing tbl features -----------------------------------------------
145
146 - implement basic non-parametric .de to support e.g. sox(1)
147 reported by naddy@ Sat, 16 Oct 2010 23:51:57 +0200
148 *** sox(1) still doesn't work, tbl(1) errors need investigation
149
150 - allow standalone `.' to be interpreted as an end-of-layout
151 delimiter instead of being thrown away as a no-op roff line
152 reported by Yuri Pankov, Wed 18 May 2011 11:34:59 CEST
153
154 --- missing misc features ----------------------------------------------
155
156 - italic correction (\/) in PostScript mode
157 Werner LEMBERG on groff at gnu dot org Sun, 10 Nov 2013 12:47:46
158
159 - The whatis(1) utility looks for whole words in Nm.
160 If the file name of a page does not agree with the contents of any
161 of its Nm macros (e.g. pool(9)), add the file name as an Nm entry
162 to the mandoc.db as well, such that whatis(1) finds it.
163 If there is a page with a file name that does not appear as a substring
164 neither in Nm nor in Nd, the same fix would allow finding that page
165 with apropos(1) using the file name as a key, as well.
166 Issue reported by tedu@ Fri, 05 Jul 2013 21:15:23 -0400
167
168 - clean up escape sequence handling, creating three classes:
169 (1) fully implemented, or parsed and ignored without loss of content
170 (2) unimplemented, potentially causing loss of content
171 or serious mangling of formatting (e.g. \n) -> ERROR
172 see textproc/mgdiff(1) for nice examples
173 (3) undefined, just output the character -> perhaps WARNING
174
175 - look at pages generated from reStructeredText, e.g. devel/mercurial hg(1)
176 These are a weird mixture of man(7) and custom autogenerated low-level
177 roff stuff. Figure out to what extent we can cope.
178 For details, see http://docutils.sourceforge.net/rst.html
179 noted by stsp@ Sat, 24 Apr 2010 09:17:55 +0200
180 reminded by nicm@ Mon, 3 May 2010 09:52:41 +0100
181
182 - look at pages generated from Texinfo source by yat2m, e.g. security/gnupg
183 First impression is not that bad.
184
185 - check compatibility with Plan9:
186 http://swtch.com/usr/local/plan9/tmac/tmac.an
187 http://swtch.com/plan9port/man/man7/man.html
188 "Anthony J. Bentley" <anthonyjbentley@gmail.com> 28 Dec 2010 21:58:40 -0700
189
190 ************************************************************************
191 * formatting issues: ugly output
192 ************************************************************************
193
194 - a column list with blank `Ta' cells triggers a spurrious
195 start-with-whitespace printing of a newline
196
197 - In .Bl -column,
198 .It Em Authentication<tab>Key Length
199 ought to render "Key Length" with emphasis, too,
200 see OpenBSD iked.conf(5).
201 reported again Nicolas Joly via wiz@ Wed, 12 Oct 2011 00:20:00 +0200
202
203 - empty phrases in .Bl column produce too few blanks
204 try e.g. .Bl -column It Ta Ta
205 reported by millert Fri, 02 Apr 2010 16:13:46 -0400
206
207 - .%T can have trailing punctuation. Currently, it puts the trailing
208 punctuation into a trailing MDOC_TEXT element inside its own scope.
209 That element should rather be outside its scope, such that the
210 punctuation does not get underlines. This is not trivial to
211 implement because .%T then needs some features of in_line_eoln() -
212 slurp all arguments into one single text element - and one feature
213 of in_line() - put trailing punctuation out of scope.
214 Found in mount_nfs(8) and exports(5), search for "Appendix".
215
216 - Trailing punctuation after .%T triggers EOS spacing, at least
217 outside .Rs (eek!). Simply setting ARGSFL_DELIM for .%T is not
218 the right solution, it sends mandoc into an endless loop.
219 reported by Nicolas Joly Sat, 17 Nov 2012 11:49:54 +0100
220
221 - in enclosures, mandoc sometimes fancies a bogus end of sentence
222 reminded by jmc@ Thu, 23 Sep 2010 18:13:39 +0059
223
224 - formatting /usr/local/man/man1/latex2man.1 with groff and mandoc
225 reveals lots of bugs both in groff and mandoc...
226 reported by bentley@ Wed, 22 May 2013 23:49:30 -0600
227
228 ************************************************************************
229 * formatting issues: gratuitous differences
230 ************************************************************************
231
232 - .Rv (and probably .Ex) print different text if an `Nm' has been named
233 or not (run a manual without `Nm blah' to see this). I'm not sure
234 that this exists in the wild, but it's still an error.
235
236 - In .Bl -bullet, the groff bullet is "+\b+\bo\bo", the mandoc bullet
237 is just "o\bo".
238 see for example OpenBSD ksh(1)
239
240 - .Pp between two .It in .Bl -column should produce one,
241 not two blank lines, see e.g. login.conf(5).
242 reported by jmc@ Sun, 17 Apr 2011 14:04:58 +0059
243 reported again by sthen@ Wed, 18 Jan 2012 02:09:39 +0000 (UTC)
244
245 - If the *first* line after .It is .Pp, break the line right after
246 the tag, do not pad with space characters before breaking.
247 See the description of the a, c, and i commands in sed(1).
248
249 - If the first line after .It is .D1, do not assert a blank line
250 in between, see for example tmux(1).
251 reported by nicm@ 13 Jan 2011 00:18:57 +0000
252
253 - Trailing punctuation after .It should trigger EOS spacing.
254 reported by Nicolas Joly Sat, 17 Nov 2012 11:49:54 +0100
255 Probably, this should be fixed somewhere in termp_it_pre(), not sure.
256
257 - .Nx 1.0a
258 should be "NetBSD 1.0A", not "NetBSD 1.0a",
259 see OpenBSD ccdconfig(8).
260
261 - In .Bl -tag, if a tag exceeds the right margin and must be continued
262 on the next line, it must be indented by -width, not width+1;
263 see "rule block|pass" in OpenBSD ifconfig(8).
264
265 - When the -width string contains macros, the macros must be rendered
266 before measuring the width, for example
267 .Bl -tag -width ".Dv message"
268 in magic(5), located in src/usr.bin/file, is the same
269 as -width 7n, not -width 11n.
270 The same applies to .Bl -column column widths;
271 reported again by Nicolas Joly Thu, 1 Mar 2012 13:41:26 +0100 via wiz@ 5 Mar
272 reported again by Franco Fichtner Fri, 27 Sep 2013 21:02:28 +0200
273 An easy partial fix would be to just skip the first word if it starts
274 with a dot, including any following white space, when measuring.
275
276 - The \& zero-width character counts as output.
277 That is, when it is alone on a line between two .Pp,
278 we want three blank lines, not two as in mandoc.
279
280 - Header lines of excessive length:
281 Port OpenBSD man_term.c rev. 1.25 to mdoc_term.c
282 and document it in mdoc(7) and man(7) COMPATIBILITY
283 found while talking to Chris Bennett
284
285 - trailing whitespace must be ignored even when followed by a font escape,
286 see for example
287 makes
288 \fBdig \fR
289 operate in batch mode
290 in dig(1).
291
292 ************************************************************************
293 * warning issues
294 ************************************************************************
295
296 - check that MANDOCERR_BADTAB is thrown in the right cases,
297 i.e. when finding a literal tab character in fill mode,
298 and possibly change the wording of the warning message
299 to refer to fill mode, not literal mode
300 See the mail from Werner LEMBERG on the groff list,
301 Fri, 14 Feb 2014 18:54:42 +0100 (CET)
302
303 ************************************************************************
304 * performance issues
305 ************************************************************************
306
307 Several areas can be cleaned up to make mandoc even faster. These are
308
309 - improve hashing mechanism for macros (quite important: performance)
310
311 - improve hashing mechanism for characters (not as important)
312
313 - the PDF file is HUGE: this can be reduced by using relative offsets
314
315 - instead of re-initialising the roff predefined-strings set before each
316 parse, create a read-only version the first time and copy it
317
318 ************************************************************************
319 * structural issues
320 ************************************************************************
321
322 - We use the input line number at several places to distinguish
323 same-line from different-line input. That plainly doesn't work
324 with user-defined macros, leading to random breakage.
325
326 - Find better ways to prevent endless loops
327 in roff(7) macro and string expansion.
328
329 - Finish cleanup of date handling.
330 Decide which formats should be recognized where.
331 Update both mdoc(7) and man(7) documentation.
332 Triggered by Tim van der Molen Tue, 22 Feb 2011 20:30:45 +0100
333
334 - Consider creating some views that will make the database more
335 readable from the sqlite3 shell. Consider using them to
336 abstract from the database structure, too.
337 suggested by espie@ Sat, 19 Apr 2014 14:52:57 +0200
338