xref: /netbsd-src/external/bsd/mdocml/dist/TODO (revision 9ff1f2ac944731963b1d62cde605dabb5cb29a3a)
10d88b603Schristos************************************************************************
20d88b603Schristos* Official mandoc TODO.
3*9ff1f2acSchristos* Id: TODO,v 1.218 2016/06/05 21:06:04 schwarze Exp
40d88b603Schristos************************************************************************
50d88b603Schristos
6fec65c98SchristosMany issues are annotated for difficulty as follows:
7fec65c98Schristos
8fec65c98Schristos - loc = locality of the issue
9fec65c98Schristos    *    single file issue, affects file only, or very few
10fec65c98Schristos    **   single module issue, affects several files of one module
11fec65c98Schristos    ***  cross-module issue, significantly impacts multiple modules
12fec65c98Schristos         and may require substantial changes to internal interfaces
13fec65c98Schristos - exist = difficulty of the existing code in this area
14fec65c98Schristos    *    affected code is straightforward and easy to read and change
15fec65c98Schristos    **   affected code is somewhat complex, but once you understand
16fec65c98Schristos         the design, not particularly difficult to understand
17fec65c98Schristos    ***  affected code uses a special, exceptionally tricky design
18fec65c98Schristos - algo = difficulty of the new algorithm to be written
19fec65c98Schristos    *    the required logic and code is straightforward
20fec65c98Schristos    **   the required logic is somewhat complex and needs a careful design
21fec65c98Schristos    ***  the required logic is exceptionally tricky,
22fec65c98Schristos         maybe an approach to solve that is not even known yet
23fec65c98Schristos - size = the amount of code to be written or changed
24fec65c98Schristos    *    a small number of lines (at most 100, usually much less)
25fec65c98Schristos    **   a considerable amount of code (several dozen to a few hundred)
26fec65c98Schristos    ***  a large amount of code (many hundreds, maybe thousands)
27fec65c98Schristos - imp = importance of the issue
28fec65c98Schristos    *    mostly for completeness
29fec65c98Schristos    **   would be nice to have
30fec65c98Schristos    ***  issue causes considerable inconvenience
31fec65c98Schristos
32fec65c98SchristosObviously, as the issues have not been solved yet, these annotations
33fec65c98Schristosare mere guesses, and some may be wrong.
34fec65c98Schristos
350d88b603Schristos************************************************************************
3670f041f9Sjoerg* crashes
370d88b603Schristos************************************************************************
380d88b603Schristos
39fec65c98Schristos- The abort() in bufcat(), html.c, can be triggered via buffmt_includes()
40fec65c98Schristos  by running -Thtml -Oincludes on a file containing a long .In argument.
41fec65c98Schristos  Fixing this will probably require reworking the whole bufcat() concept.
42fec65c98Schristos  loc **  exist *  algo *  size **  imp **
430d88b603Schristos
440d88b603Schristos************************************************************************
450d88b603Schristos* missing features
460d88b603Schristos************************************************************************
470d88b603Schristos
480d88b603Schristos--- missing roff features ----------------------------------------------
490d88b603Schristos
500d88b603Schristos- .ad (adjust margins)
510d88b603Schristos  .ad l -- adjust left margin only (flush left)
520d88b603Schristos  .ad r -- adjust right margin only (flush right)
530d88b603Schristos  .ad c -- center text on line
540d88b603Schristos  .ad b -- adjust both margins (alias: .ad n)
550d88b603Schristos  .na   -- temporarily disable adjustment without changing the mode
560d88b603Schristos  .ad   -- re-enable adjustment without changing the mode
570d88b603Schristos  Adjustment mode is ignored while in no-fill mode (.nf).
58fec65c98Schristos  loc ***  exist ***  algo **  size **  imp **  (parser reorg would help)
5970f041f9Sjoerg
6070f041f9Sjoerg- .fc (field control)
6170f041f9Sjoerg  found by naddy@ in xloadimage(1)
62fec65c98Schristos  loc **  exist ***  algo *  size *  imp *
6370f041f9Sjoerg
6470f041f9Sjoerg- .nr third argument (auto-increment step size, requires \n+)
6570f041f9Sjoerg  found by bentley@ in sbcl(1)  Mon, 9 Dec 2013 18:36:57 -0700
66fec65c98Schristos  loc *  exist *  algo *  size *  imp **
670d88b603Schristos
680d88b603Schristos- .ns (no-space mode) occurs in xine-config(1)
69*9ff1f2acSchristos  when implementing this, also let .TH set it
700d88b603Schristos  reported by brad@  Sat, 15 Jan 2011 15:45:23 -0500
71fec65c98Schristos  loc ***  exist ***  algo ***  size **  imp *
720d88b603Schristos
73fec65c98Schristos- .ta (tab settings)
74fec65c98Schristos  #1 most important issue naddy@ Mon, 16 Feb 2015 20:59:17 +0100
75fec65c98Schristos  ircbug(1) gnats(1) reported by brad@  Sat, 15 Jan 2011 15:50:51 -0500
76fec65c98Schristos  also Tcl_NewStringObj(3) via wiz@  Wed, 5 Mar 2014 22:27:43 +0100
77fec65c98Schristos  also posix2time(3) Carsten Kunze  Mon, 1 Dec 2014 13:03:10 +0100
78fec65c98Schristos  loc **  exist ***  algo **  size **  imp ***
790d88b603Schristos
8070f041f9Sjoerg- .ti (temporary indent)
81fec65c98Schristos  found by naddy@ in xloadimage(1) [devel/libvstr] vstr(3)
8270f041f9Sjoerg  found by bentley@ in nmh(1)  Mon, 23 Apr 2012 13:38:28 -0600
83fec65c98Schristos  loc **  exist **  algo **  size *  imp ** (parser reorg helps a lot)
8470f041f9Sjoerg
8570f041f9Sjoerg- .while and .shift
8670f041f9Sjoerg  found by jca@ in ratpoison(1)  Sun, 30 Jun 2013 12:01:09 +0200
87fec65c98Schristos  loc *  exist **  algo **  size **  imp **
8870f041f9Sjoerg
8970f041f9Sjoerg- \h horizontal move
90fec65c98Schristos  #2 most important issue naddy@  Mon, 16 Feb 2015 20:59:17 +0100
91fec65c98Schristos  found in cclive(1) nasm(1) bogofilter(1) asciidoc/DocBook output
92fec65c98Schristos  bentley@ on discuss@  Sat, 21 Sep 2013 22:29:34 -0600
93fec65c98Schristos  naddy@  Thu, 4 Dec 2014 16:26:41 +0100
94fec65c98Schristos  loc **  exist **  algo **  size *  imp *** (parser reorg helps a lot)
9570f041f9Sjoerg
9670f041f9Sjoerg- \n+ and \n- numerical register increment and decrement
9770f041f9Sjoerg  found by bentley@ in sbcl(1)  Mon, 9 Dec 2013 18:36:57 -0700
98fec65c98Schristos  loc *  exist *  algo *  size *  imp **
99fec65c98Schristos
100fec65c98Schristos- \n(.$ macro argument count number register; ocserv(8) by autogen
101fec65c98Schristos  found by sthen@  Thu, 19 Feb 2015 22:03:01 +0000
102fec65c98Schristos  loc *  exist **  algo *  size *  imp **
103fec65c98Schristos
104fec65c98Schristos- \w'' improve width measurements
105fec65c98Schristos  would not be very useful without an expression parser, see below
106fec65c98Schristos  needed for Tcl_NewStringObj(3) via wiz@  Wed, 5 Mar 2014 22:27:43 +0100
107fec65c98Schristos  loc **  exist ***  algo ***  size *  imp ***
1080d88b603Schristos
109*9ff1f2acSchristos- \\ in high-level macro arguments
110*9ff1f2acSchristos  Currently, \\ is expanded in two situations:
111*9ff1f2acSchristos  1) macro and string definition (roff.c setstrn())
112*9ff1f2acSchristos  2) macro argument parsing (mandoc.c mandoc_getarg())
113*9ff1f2acSchristos  For user defined macros, the second happens in time because of ROFF_REPARSE.
114*9ff1f2acSchristos  But for standard high-level macros, it only happens after entering the
115*9ff1f2acSchristos  high level parsers, which is too late because the code doesn't get
116*9ff1f2acSchristos  back to roff.c roff_res() from that point.  Because this requires
117*9ff1f2acSchristos  distinguishing requests, user-defined macros and standard macros
118*9ff1f2acSchristos  on the roff_res() level, it is hard to solve without the parser reorg.
119*9ff1f2acSchristos  Found by naddy@ in devel/cutils cobfusc(1)  Mon, 16 Feb 2015 19:10:52 +0100
120*9ff1f2acSchristos  loc ***  exist ***  algo ***  size **  imp *
121*9ff1f2acSchristos
1220d88b603Schristos- using undefined strings or macros defines them to be empty
1230d88b603Schristos  wl@  Mon, 14 Nov 2011 14:37:01 +0000
124fec65c98Schristos  loc *  exist *  algo *  size *  imp *
1250d88b603Schristos
1260d88b603Schristos--- missing mdoc features ----------------------------------------------
1270d88b603Schristos
1280d88b603Schristos- .Bl -column .Xo support is missing
1290d88b603Schristos  ultimate goal:
1300d88b603Schristos  restore .Xr and .Dv to
1310d88b603Schristos  lib/libc/compat-43/sigvec.3
1320d88b603Schristos  lib/libc/gen/signal.3
1330d88b603Schristos  lib/libc/sys/sigaction.2
134fec65c98Schristos  loc *  exist ***  algo ***  size *  imp **
1350d88b603Schristos
1360d88b603Schristos- edge case: decide how to deal with blk_full bad nesting, e.g.
1370d88b603Schristos  .Sh .Nm .Bk .Nm .Ek .Sh found by jmc@ in ssh-keygen(1)
1380d88b603Schristos  from jmc@  Wed, 14 Jul 2010 18:10:32 +0100
139fec65c98Schristos  loc *  exist ***  algo ***  size **  imp **
1400d88b603Schristos
141fec65c98Schristos- .Bd -centered implies -filled, not -unfilled, which is not
142fec65c98Schristos  easy to implement; it requires code similar to .ce, which
143fec65c98Schristos  we don't have either.
144fec65c98Schristos  Besides, groff has bug causing text right *before* .Bd -centered
145fec65c98Schristos  to be centered as well.
146fec65c98Schristos  loc ***  exist ***  algo **  size **  imp **  (parser reorg would help)
1470d88b603Schristos
1480d88b603Schristos- .Bd -filled should not be the same as .Bd -ragged, but align both
1490d88b603Schristos  the left and right margin.  In groff, it is implemented in terms
1500d88b603Schristos  of .ad b, which we don't have either.  Found in cksum(1).
151fec65c98Schristos  loc ***  exist ***  algo **  size **  imp **  (parser reorg would help)
1520d88b603Schristos
1530d88b603Schristos- implement blank `Bl -column', such as
1540d88b603Schristos  .Bl -column
1550d88b603Schristos  .It foo Ta bar
1560d88b603Schristos  .El
157fec65c98Schristos  loc *  exist ***  algo ***  size *  imp *
1580d88b603Schristos
1590d88b603Schristos- explicitly disallow nested `Bl -column', which would clobber internal
1600d88b603Schristos  flags defined for struct mdoc_macro
161fec65c98Schristos  loc *  exist *  algo *  size *  imp **
1620d88b603Schristos
1630d88b603Schristos- In .Bl -column .It, the end of the line probably has to be regarded
1640d88b603Schristos  as an implicit .Ta, if there could be one, see the following mildly
1650d88b603Schristos  ugly code from login.conf(5):
1660d88b603Schristos    .Bl -column minpasswordlen program xetcxmotd
1670d88b603Schristos    .It path Ta path Ta value of Dv _PATH_DEFPATH
1680d88b603Schristos    .br
1690d88b603Schristos    Default search path.
1700d88b603Schristos  reported by Michal Mazurek <akfaew at jasminek dot net>
1710d88b603Schristos  via jmc@ Thu, 7 Apr 2011 16:00:53 +0059
172fec65c98Schristos  loc *  exist ***  algo **  size *  imp **
1730d88b603Schristos
1740d88b603Schristos- inside `.Bl -column' phrases, punctuation is handled like normal
1750d88b603Schristos  text, e.g. `.Bl -column .It Fl x . Ta ...' should give "-x -."
1760d88b603Schristos
1770d88b603Schristos- inside `.Bl -column' phrases, TERMP_IGNDELIM handling by `Pf'
1780d88b603Schristos  is not safe, e.g. `.Bl -column .It Pf a b .' gives "ab."
1790d88b603Schristos  but should give "ab ."
1800d88b603Schristos
181fec65c98Schristos- check whether it is correct that `D1' uses INDENT+1;
182fec65c98Schristos  does it need its own constant?
183fec65c98Schristos  loc *  exist **  algo **  size *  imp **
1840d88b603Schristos
1850d88b603Schristos- prohibit `Nm' from having non-text HEAD children
1860d88b603Schristos  (e.g., NetBSD mDNSShared/dns-sd.1)
1870d88b603Schristos  (mdoc_html.c and mdoc_term.c `Nm' handlers can be slightly simplified)
1880d88b603Schristos
189fec65c98Schristos- support translated section names
190fec65c98Schristos  e.g. x11/scrotwm scrotwm_es.1:21:2: error: NAME section must be first
191fec65c98Schristos  that one uses NOMBRE because it is spanish...
192fec65c98Schristos  deraadt tends to think that section-dependent macro behaviour
193fec65c98Schristos  is a bad idea in the first place, so this may be irrelevant
194fec65c98Schristos  loc **  exist **  algo **  size *  imp **
195fec65c98Schristos
1960d88b603Schristos- When there is free text in the SYNOPSIS and that free text contains
1970d88b603Schristos  the .Nm macro, groff somehow understands to treat the .Nm as an in-line
1980d88b603Schristos  macro, while mandoc treats it as a block macro and breaks the line.
1990d88b603Schristos  No idea how the logic for distinguishing in-line and block instances
2000d88b603Schristos  should be, needs investigation.
2010d88b603Schristos  uqs@  Thu, 2 Jun 2011 11:03:51 +0200
2020d88b603Schristos  uqs@  Thu, 2 Jun 2011 11:33:35 +0200
203fec65c98Schristos  loc *  exist **  algo ***  size *  imp **
2040d88b603Schristos
2050d88b603Schristos--- missing man features -----------------------------------------------
2060d88b603Schristos
2070d88b603Schristos- -T[x]html doesn't stipulate non-collapsing spaces in literal mode
2080d88b603Schristos
2090d88b603Schristos--- missing tbl features -----------------------------------------------
2100d88b603Schristos
211*9ff1f2acSchristos- horizontal lines in the layout still consume data cells
212*9ff1f2acSchristos  and can be mixed with actual data on the same table line
213*9ff1f2acSchristos  synaptics(4) found by tedu@  Mon, 17 Aug 2015 21:17:42 -0400
214*9ff1f2acSchristos  loc **  exist **  algo **  size **  imp ***
215*9ff1f2acSchristos
216*9ff1f2acSchristos- the "w" layout option is ignored
217*9ff1f2acSchristos  synaptics(4) found by tedu@  Mon, 17 Aug 2015 21:17:42 -0400
218*9ff1f2acSchristos  loc *  exist *  algo *  size *  imp **
219*9ff1f2acSchristos
220*9ff1f2acSchristos- the "s" layout column specifier is used for placement of data
221*9ff1f2acSchristos  into columns, but ignored during column width calculations
222*9ff1f2acSchristos  synaptics(4) found by tedu@  Mon, 17 Aug 2015 21:17:42 -0400
223*9ff1f2acSchristos  loc *  exist **  algo ***  size *  imp **
224*9ff1f2acSchristos
225*9ff1f2acSchristos- support mdoc(7) and man(7) macros inside tbl(7) code;
226*9ff1f2acSchristos  probably requires the parser reorg and letting tbl(7)
227*9ff1f2acSchristos  use roff_node such that macro sets can mix;
228*9ff1f2acSchristos  informed by bapt@ that FreeBSD needs this.
229*9ff1f2acSchristos  loc ***  exist **  algo ***  size **  imp ***
230*9ff1f2acSchristos
231fec65c98Schristos- look at the POSIX manuals in the books/man-pages-posix port,
232fec65c98Schristos  they use some unsupported tbl(7) features.
233fec65c98Schristos  loc *  exist **  algo **  size **  imp ***
234fec65c98Schristos
235fec65c98Schristos- use Unicode U+2500 to U+256C for table borders
236fec65c98Schristos  in tbl(7) -Tutf-8 output
237fec65c98Schristos  suggested by bentley@  Tue, 14 Oct 2014 04:10:55 -0600
238fec65c98Schristos  loc *  exist **  algo *  size *  imp **
2390d88b603Schristos
240fec65c98Schristos--- missing eqn features -----------------------------------------------
241fec65c98Schristos
242*9ff1f2acSchristos- In a matrix, break the output line after each matrix line.
243*9ff1f2acSchristos  Found in the discussion at CDBUG 2015.
244*9ff1f2acSchristos  Suggested by Avi Weinstock.
245*9ff1f2acSchristos  loc *  exist *  algo *  size *  imp **
246*9ff1f2acSchristos
247fec65c98Schristos- The "size" keyword is parsed, but ignored by the formatter.
248fec65c98Schristos  loc *  exist *  algo *  size *  imp *
249fec65c98Schristos
250fec65c98Schristos- The spacing characters `~', `^', and tab are currently ignored,
251fec65c98Schristos  see User's Guide (Second Edition) page 2 section 4.
252fec65c98Schristos  loc *  exist *  algo **  size *  imp **
253fec65c98Schristos
254fec65c98Schristos- Mark and lineup are parsed and ignored,
255fec65c98Schristos  see User's Guide (Second Edition) page 5 section 15.
256fec65c98Schristos  loc **  exist **  algo **  size **  imp **
2570d88b603Schristos
2580d88b603Schristos--- missing misc features ----------------------------------------------
2590d88b603Schristos
26070f041f9Sjoerg- italic correction (\/) in PostScript mode
26170f041f9Sjoerg  Werner LEMBERG on groff at gnu dot org  Sun, 10 Nov 2013 12:47:46
262fec65c98Schristos  loc **  exist **  algo *  size *  imp *
26370f041f9Sjoerg
264*9ff1f2acSchristos- change the default PAGER to more -Es and use the pager
265*9ff1f2acSchristos  even for apropos title line output; req by bapt@
266*9ff1f2acSchristos  loc *  exist *  algo *  size *  imp ***
267fec65c98Schristos
268fec65c98Schristos- makewhatis(8) for preformatted pages:
269fec65c98Schristos  parse the section number from the header line
270fec65c98Schristos  and compare to the section number from the directory name
271fec65c98Schristos  loc *  exist *  algo *  size *  imp **
272fec65c98Schristos
273fec65c98Schristos- Does makewhatis(8) detect missing NAME sections, missing names,
274fec65c98Schristos  and missing descriptions in all the file formats?
275fec65c98Schristos  loc *  exist *  algo *  size *  imp ***
27670f041f9Sjoerg
2770d88b603Schristos- clean up escape sequence handling, creating three classes:
2780d88b603Schristos  (1) fully implemented, or parsed and ignored without loss of content
2790d88b603Schristos  (2) unimplemented, potentially causing loss of content
2800d88b603Schristos      or serious mangling of formatting (e.g. \n) -> ERROR
2810d88b603Schristos      see textproc/mgdiff(1) for nice examples
2820d88b603Schristos  (3) undefined, just output the character -> perhaps WARNING
283fec65c98Schristos  loc ***  exist **  algo **  size **  imp *** (parser reorg helps)
284fec65c98Schristos
285fec65c98Schristos- kettenis wants base roff, ms, and me  Fri, 1 Jan 2010 22:13:15 +0100 (CET)
286fec65c98Schristos  loc **  exist **  algo **  size ***  imp *
287fec65c98Schristos
288*9ff1f2acSchristos- Vsevolod Stakhov (FreeBSD) needs either a markdown output formatter
289*9ff1f2acSchristos  for mandoc -mdoc or a markdown to mdoc converter because they
290*9ff1f2acSchristos  have to maintain manuals needed both in markdown and mdoc format.
291*9ff1f2acSchristos  Look at the libsoldout (markdown -> whatever)
292*9ff1f2acSchristos  loc *  exist *  algo *  size **  imp **
293fec65c98Schristos
294*9ff1f2acSchristos--- compatibility checks -----------------------------------------------
295fec65c98Schristos
296fec65c98Schristos- is .Bk implemented correctly in modern groff?
297fec65c98Schristos  sobrado@  Tue, 19 Apr 2011 22:12:55 +0200
298fec65c98Schristos
299fec65c98Schristos- compare output to Heirloom roff, Solaris roff, and
300fec65c98Schristos  http://repo.or.cz/w/neatroff.git  http://litcave.rudi.ir/
301fec65c98Schristos
302fec65c98Schristos- look at AT&T DWB http://www2.research.att.com/sw/download
303fec65c98Schristos  Carsten Kunze <carsten dot kunze at arcor dot de> has patches
304fec65c98Schristos  Mon, 4 Aug 2014 17:01:28 +0200
3050d88b603Schristos
3060d88b603Schristos- look at pages generated from reStructeredText, e.g. devel/mercurial hg(1)
3070d88b603Schristos  These are a weird mixture of man(7) and custom autogenerated low-level
3080d88b603Schristos  roff stuff.  Figure out to what extent we can cope.
3090d88b603Schristos  For details, see http://docutils.sourceforge.net/rst.html
3100d88b603Schristos  noted by stsp@  Sat, 24 Apr 2010 09:17:55 +0200
3110d88b603Schristos  reminded by nicm@  Mon, 3 May 2010 09:52:41 +0100
3120d88b603Schristos
313fec65c98Schristos- look at pages generated from ronn(1) github.com/rtomayko/ronn
314fec65c98Schristos  (based on markdown)
315fec65c98Schristos
31670f041f9Sjoerg- look at pages generated from Texinfo source by yat2m, e.g. security/gnupg
31770f041f9Sjoerg  First impression is not that bad.
31870f041f9Sjoerg
319fec65c98Schristos- look at pages generated by pandoc; see
320fec65c98Schristos  https://github.com/jgm/pandoc/blob/master/src/Text/Pandoc/Writers/Man.hs
321fec65c98Schristos  porting planned by kili@  Thu, 19 Jun 2014 19:46:28 +0200
322fec65c98Schristos
3230d88b603Schristos- check compatibility with Plan9:
3240d88b603Schristos  http://swtch.com/usr/local/plan9/tmac/tmac.an
3250d88b603Schristos  http://swtch.com/plan9port/man/man7/man.html
3260d88b603Schristos  "Anthony J. Bentley" <anthonyjbentley@gmail.com> 28 Dec 2010 21:58:40 -0700
3270d88b603Schristos
328*9ff1f2acSchristos- check compatibility with COHERENT troff:
329*9ff1f2acSchristos  http://www.nesssoftware.com/home/mwc/source.php
330*9ff1f2acSchristos
331fec65c98Schristos- check compatibility with the man(7) formatter
332fec65c98Schristos  https://raw.githubusercontent.com/rofl0r/hardcore-utils/master/man.c
333fec65c98Schristos
334fec65c98Schristos- check compatibility with
335fec65c98Schristos  http://ikiwiki.info/plugins/contrib/mandoc/
336fec65c98Schristos  https://github.com/schmonz/ikiwiki/compare/mandoc
337fec65c98Schristos  Amitai Schlair  Mon, 19 May 2014 14:05:53 -0400
338fec65c98Schristos
3390d88b603Schristos************************************************************************
3400d88b603Schristos* formatting issues: ugly output
3410d88b603Schristos************************************************************************
3420d88b603Schristos
343fec65c98Schristos- revisit empty in-line macros
344fec65c98Schristos  look at the difference between "Em x Em ." and "Sq x Em ."
345fec65c98Schristos  Carsten Kunze  Fri, 12 Dec 2014 00:15:41 +0100
346fec65c98Schristos  loc *** exist *** algo *** size * imp **
347fec65c98Schristos
348fec65c98Schristos- a column list with blank `Ta' cells triggers a spurious
3490d88b603Schristos  start-with-whitespace printing of a newline
3500d88b603Schristos
351fec65c98Schristos- In .Bl -column, .It a<tab>"b<tab>c"
352fec65c98Schristos  shows the quotes in groff, but not in mandoc
353fec65c98Schristos  loc * exist *** algo ** size * imp **
354fec65c98Schristos
3550d88b603Schristos- In .Bl -column,
3560d88b603Schristos  .It Em Authentication<tab>Key Length
3570d88b603Schristos  ought to render "Key Length" with emphasis, too,
3580d88b603Schristos  see OpenBSD iked.conf(5).
3590d88b603Schristos  reported again Nicolas Joly via wiz@ Wed, 12 Oct 2011 00:20:00 +0200
360fec65c98Schristos  loc *  exist ***  algo ***  size **  imp ***
3610d88b603Schristos
3620d88b603Schristos- empty phrases in .Bl column produce too few blanks
3630d88b603Schristos  try e.g. .Bl -column It Ta Ta
3640d88b603Schristos  reported by millert Fri, 02 Apr 2010 16:13:46 -0400
365fec65c98Schristos  loc *  exist ***  algo ***  size *  imp **
3660d88b603Schristos
3670d88b603Schristos- .%T can have trailing punctuation.  Currently, it puts the trailing
3680d88b603Schristos  punctuation into a trailing MDOC_TEXT element inside its own scope.
3690d88b603Schristos  That element should rather be outside its scope, such that the
3700d88b603Schristos  punctuation does not get underlines.  This is not trivial to
3710d88b603Schristos  implement because .%T then needs some features of in_line_eoln() -
3720d88b603Schristos  slurp all arguments into one single text element - and one feature
3730d88b603Schristos  of in_line() - put trailing punctuation out of scope.
3740d88b603Schristos  Found in mount_nfs(8) and exports(5), search for "Appendix".
375fec65c98Schristos  loc **  exist **  algo ***  size *  imp **
3760d88b603Schristos
37770f041f9Sjoerg- Trailing punctuation after .%T triggers EOS spacing, at least
37870f041f9Sjoerg  outside .Rs (eek!).  Simply setting ARGSFL_DELIM for .%T is not
37970f041f9Sjoerg  the right solution, it sends mandoc into an endless loop.
38070f041f9Sjoerg  reported by Nicolas Joly  Sat, 17 Nov 2012 11:49:54 +0100
381fec65c98Schristos  loc *  exist **  algo **  size *  imp **
382fec65c98Schristos
383fec65c98Schristos- global variables in the SYNOPSIS of section 3 pages
384fec65c98Schristos  .Vt vs .Vt/.Va vs .Ft/.Va vs .Ft/.Fa ...
385fec65c98Schristos  from kristaps@  Tue, 08 Jun 2010 11:13:32 +0200
38670f041f9Sjoerg
3870d88b603Schristos- in enclosures, mandoc sometimes fancies a bogus end of sentence
3880d88b603Schristos  reminded by jmc@  Thu, 23 Sep 2010 18:13:39 +0059
389fec65c98Schristos  loc *  exist **  algo ***  size *  imp ***
390fec65c98Schristos
391fec65c98Schristos- a line starting with "\fB something" counts as starting with whitespace
392fec65c98Schristos  and triggers a line break; found in audio/normalize-mp3(1)
393fec65c98Schristos  loc **  exist *  algo **  size *  imp **
3940d88b603Schristos
39570f041f9Sjoerg- formatting /usr/local/man/man1/latex2man.1 with groff and mandoc
39670f041f9Sjoerg  reveals lots of bugs both in groff and mandoc...
39770f041f9Sjoerg  reported by bentley@  Wed, 22 May 2013 23:49:30 -0600
39870f041f9Sjoerg
399fec65c98Schristos--- PDF issues ---------------------------------------------------------
400fec65c98Schristos
401fec65c98Schristos- PDF output doesn't use a monospaced font for .Bd -literal
402fec65c98Schristos  Example: "mandoc -Tpdf afterboot.8 > output.pdf && pdfviewer output.pdf".
403fec65c98Schristos  Search the text "Routing tables".
404fec65c98Schristos  Also check what PostScript mode does when fixing this.
405fec65c98Schristos  reported by juanfra@ Wed, 04 Jun 2014 21:44:58 +0200
406fec65c98Schristos  instructions from juanfra@  Wed, 11 Jun 2014 02:21:01 +0200
407fec65c98Schristos    add a new <</Type /Font>> block to the PDF files with /BaseFont /Courier
408fec65c98Schristos    and change the /Name from /F0 to the new font (/F5 (?)).
409fec65c98Schristos  loc *  exist **  algo **  size *  imp **
410fec65c98Schristos
411fec65c98Schristos--- HTML issues --------------------------------------------------------
412fec65c98Schristos
413fec65c98Schristos- <dl><dt><dd> formatting is ugly
414fec65c98Schristos  hints are easy to find on the web, e.g.
415fec65c98Schristos  http://stackoverflow.com/questions/1713048/
416fec65c98Schristos  see also matthew@  Fri, 18 Jul 2014 19:25:12 -0700
417fec65c98Schristos  loc *  exist *  algo **  size *  imp ***
418fec65c98Schristos
419*9ff1f2acSchristos- In -man -Thtml, .nf does not preserve indentation.
420*9ff1f2acSchristos  It should either convert blanks to &nbsp;
421*9ff1f2acSchristos  or use <pre> rather than <div> (like .Bd -literal does).
422*9ff1f2acSchristos  Reported by afresh1@  12 Apr 2016 14:35:45 -0700
423*9ff1f2acSchristos
424*9ff1f2acSchristos- .Bf at the beginning of a paragraph inserts a bogus 1ex horizontal
425*9ff1f2acSchristos  space, see for example random(3).  Introduced in
426*9ff1f2acSchristos  http://mdocml.bsd.lv/cgi-bin/cvsweb/mdoc_html.c.diff?r1=1.91&r2=1.92
427*9ff1f2acSchristos  reported by deraadt@ Mon, 28 Sep 2015 20:14:13 -0600 (MDT)
428*9ff1f2acSchristos  loc **  exist **  algo **  size *  imp *
429*9ff1f2acSchristos
430fec65c98Schristos- jsg on icb, Nov 3, 2014:
431fec65c98Schristos  try to guess Xr in man(7) for hyperlinking
432fec65c98Schristos
433fec65c98Schristos- The tables used to render the three-part page headers actually force
434fec65c98Schristos  the width of the <body> to the max-width given for <html>.
435fec65c98Schristos  Not yet sure how to fix that...
436fec65c98Schristos  Observed by an Anonymous Coward on undeadly.org:
437fec65c98Schristos  http://undeadly.org/cgi?action=article&sid=20140925064244&pid=1
438fec65c98Schristos  loc *  exist *  algo **  size *  imp ***
439fec65c98Schristos
440fec65c98Schristos- consider whether <var> can be used for Ar Dv Er Ev Fa Va.
441fec65c98Schristos  from bentley@  Wed, 13 Aug 2014 09:17:55 -0600
442fec65c98Schristos
443*9ff1f2acSchristos- generate <img> tags in HTML
444*9ff1f2acSchristos  idea from florian@  Tue, 7 Apr 2015 00:26:28 +0000
445*9ff1f2acSchristos  may be possible to implement with .Lk img://something.png alt_text
446*9ff1f2acSchristos
447fec65c98Schristos- check https://github.com/trentm/mdocml
448fec65c98Schristos
4490d88b603Schristos************************************************************************
4500d88b603Schristos* formatting issues: gratuitous differences
4510d88b603Schristos************************************************************************
4520d88b603Schristos
453fec65c98Schristos- .Fn reopens a new scope after punctuation in mandoc,
454fec65c98Schristos  but closes its scope for good in groff.
455fec65c98Schristos  Do we want to change mandoc or groff?
456fec65c98Schristos  Steffen Nurpmeso  Sat, 08 Nov 2014 13:34:59 +0100
457fec65c98Schristos  loc *  exist **  algo **  size *  imp **
4580d88b603Schristos
459fec65c98Schristos- In .Bl -enum -width 0n, groff continues one the same line after
460fec65c98Schristos  the number, mandoc breaks the line.
461fec65c98Schristos  mail to kristaps@  Mon, 20 Jul 2009 02:21:39 +0200
462fec65c98Schristos  loc *  exist **  algo **  size *  imp **
4630d88b603Schristos
4640d88b603Schristos- .Pp between two .It in .Bl -column should produce one,
4650d88b603Schristos  not two blank lines, see e.g. login.conf(5).
4660d88b603Schristos  reported by jmc@  Sun, 17 Apr 2011 14:04:58 +0059
4670d88b603Schristos  reported again by sthen@  Wed, 18 Jan 2012 02:09:39 +0000 (UTC)
468fec65c98Schristos  loc *  exist ***  algo **  size *  imp **
4690d88b603Schristos
4700d88b603Schristos- If the *first* line after .It is .Pp, break the line right after
4710d88b603Schristos  the tag, do not pad with space characters before breaking.
4720d88b603Schristos  See the description of the a, c, and i commands in sed(1).
473fec65c98Schristos  loc *  exist **  algo **  size *  imp **
4740d88b603Schristos
4750d88b603Schristos- If the first line after .It is .D1, do not assert a blank line
4760d88b603Schristos  in between, see for example tmux(1).
4770d88b603Schristos  reported by nicm@  13 Jan 2011 00:18:57 +0000
478fec65c98Schristos  loc *  exist **  algo **  size *  imp **
4790d88b603Schristos
48070f041f9Sjoerg- Trailing punctuation after .It should trigger EOS spacing.
48170f041f9Sjoerg  reported by Nicolas Joly  Sat, 17 Nov 2012 11:49:54 +0100
48270f041f9Sjoerg  Probably, this should be fixed somewhere in termp_it_pre(), not sure.
483fec65c98Schristos  loc *  exist **  algo **  size *  imp **
48470f041f9Sjoerg
4850d88b603Schristos- .Nx 1.0a
4860d88b603Schristos  should be "NetBSD 1.0A", not "NetBSD 1.0a",
4870d88b603Schristos  see OpenBSD ccdconfig(8).
488fec65c98Schristos  loc *  exist *  algo *  size *  imp **
4890d88b603Schristos
4900d88b603Schristos- In .Bl -tag, if a tag exceeds the right margin and must be continued
4910d88b603Schristos  on the next line, it must be indented by -width, not width+1;
4920d88b603Schristos  see "rule block|pass" in OpenBSD ifconfig(8).
493fec65c98Schristos  loc *  exist ***  algo **  size *  imp **
4940d88b603Schristos
4950d88b603Schristos- When the -width string contains macros, the macros must be rendered
4960d88b603Schristos  before measuring the width, for example
4970d88b603Schristos    .Bl -tag -width ".Dv message"
4980d88b603Schristos  in magic(5), located in src/usr.bin/file, is the same
4990d88b603Schristos  as -width 7n, not -width 11n.
5000d88b603Schristos  The same applies to .Bl -column column widths;
5010d88b603Schristos  reported again by Nicolas Joly Thu, 1 Mar 2012 13:41:26 +0100 via wiz@ 5 Mar
50270f041f9Sjoerg  reported again by Franco Fichtner Fri, 27 Sep 2013 21:02:28 +0200
503fec65c98Schristos  loc ***  exist ***  algo ***  size **  imp ***
50470f041f9Sjoerg  An easy partial fix would be to just skip the first word if it starts
50570f041f9Sjoerg  with a dot, including any following white space, when measuring.
506fec65c98Schristos  loc *  exist *  algo *  size *  imp ***
5070d88b603Schristos
5080d88b603Schristos- The \& zero-width character counts as output.
5090d88b603Schristos  That is, when it is alone on a line between two .Pp,
5100d88b603Schristos  we want three blank lines, not two as in mandoc.
511fec65c98Schristos  loc **  exist **  algo **  size *  imp **
5120d88b603Schristos
5130d88b603Schristos- Header lines of excessive length:
5140d88b603Schristos  Port OpenBSD man_term.c rev. 1.25 to mdoc_term.c
5150d88b603Schristos  and document it in mdoc(7) and man(7) COMPATIBILITY
5160d88b603Schristos  found while talking to Chris Bennett
517fec65c98Schristos  loc *  exist *  algo *  size *  imp *
5180d88b603Schristos
519*9ff1f2acSchristos- Sequences of multiple man(7) paragraphs (.PP, .IP) interspersed
520*9ff1f2acSchristos  with .ps and .nf/.fi produce execessive blank lines, see libJudy
521*9ff1f2acSchristos  and graphics/dcmtk.  The parser reorg may help with this.
522*9ff1f2acSchristos
5230d88b603Schristos- trailing whitespace must be ignored even when followed by a font escape,
5240d88b603Schristos  see for example
5250d88b603Schristos    makes
5260d88b603Schristos    \fBdig \fR
5270d88b603Schristos    operate in batch mode
5280d88b603Schristos  in dig(1).
529fec65c98Schristos  loc **  exist **  algo **  size *  imp **
530fec65c98Schristos
531fec65c98Schristos************************************************************************
532*9ff1f2acSchristos* portability
533*9ff1f2acSchristos************************************************************************
534*9ff1f2acSchristos
535*9ff1f2acSchristos- systems having UTF-8 but not en_US.UTF-8
536*9ff1f2acSchristos  call locale(1) from ./configure, select a UTF-8-locale,
537*9ff1f2acSchristos  and use that for test-wchar.c and term_ascii.c
538*9ff1f2acSchristos  to Markus Waldeck  Sat, 18 Jul 2015 01:55:37 +0200
539*9ff1f2acSchristos  loc *  exist *  algo *  size *  imp *
540*9ff1f2acSchristos
541*9ff1f2acSchristos************************************************************************
542fec65c98Schristos* warning issues
543fec65c98Schristos************************************************************************
544fec65c98Schristos
545*9ff1f2acSchristos- provide a way in mandoc(1) to warn about broken .Xr links;
546*9ff1f2acSchristos  probably cannot be on by default in -Tlint because it needs
547*9ff1f2acSchristos  to access the manpath and mandoc.db(3) after parsing.
548*9ff1f2acSchristos  asked for by jmc@ Fri, 4 Dec 2015 22:39:40 +0000
549*9ff1f2acSchristos
550*9ff1f2acSchristos- Report errors in -O suboption parsing.
551*9ff1f2acSchristos  loc *  exist *  algo *  size *  imp **
552*9ff1f2acSchristos
553*9ff1f2acSchristos- warn when .Sh or .Ss contain other macros
554*9ff1f2acSchristos  Steffen Nurpmeso, savannah.gnu.org/bugs/index.php?45034
555*9ff1f2acSchristos  loc *  exist *  algo *  size *  imp **
556*9ff1f2acSchristos
557fec65c98Schristos- check that MANDOCERR_BADTAB is thrown in the right cases,
558fec65c98Schristos  i.e. when finding a literal tab character in fill mode,
559fec65c98Schristos  and possibly change the wording of the warning message
560fec65c98Schristos  to refer to fill mode, not literal mode
561fec65c98Schristos  See the mail from Werner LEMBERG on the groff list,
562fec65c98Schristos  Fri, 14 Feb 2014 18:54:42 +0100 (CET)
563fec65c98Schristos  loc *  exist **  algo **  size *  imp **
564fec65c98Schristos
565fec65c98Schristos- warn about attempts to call non-callable macros
566fec65c98Schristos  Steffen Nurpmeso  Tue, 11 Nov 2014 22:55:16 +0100
567fec65c98Schristos  Note that formatting is inconsistent in groff.
568fec65c98Schristos  .Fn Po prints "Po()", .Ar Sh prints "file ..." and no "Sh".
569fec65c98Schristos  Relatively hard because the relevant code is scattered
570fec65c98Schristos  all over mdoc_macro.c and all subtly different.
571fec65c98Schristos  loc **  exist **  algo **  size **  imp **
572fec65c98Schristos
573fec65c98Schristos- warn about "new sentence, new line"
574fec65c98Schristos  loc **  exist **  algo ***  size *  imp **
575fec65c98Schristos
576fec65c98Schristos- mandoc_special does not really check the escape sequence,
577fec65c98Schristos  but just the overall format
578fec65c98Schristos  loc **  exist **  algo ***  size **  imp **
579fec65c98Schristos
580fec65c98Schristos- integrate mdoclint into mandoc ("end-of-line whitespace" thread)
581fec65c98Schristos  from jmc@  Mon, 13 Jul 2009 17:12:09 +0100
582fec65c98Schristos  from kristaps@  Mon, 13 Jul 2009 18:34:53 +0200
583fec65c98Schristos  from jmc@  Mon, 13 Jul 2009 17:45:37 +0059
584fec65c98Schristos  from kristaps@  Mon, 13 Jul 2009 19:02:03 +0200
585fec65c98Schristos  (mostly done, check what remains)
586fec65c98Schristos
587fec65c98Schristos- -Tlint parser errors and warnings to stdout
588fec65c98Schristos  to tech@mdocml, naddy@  Wed, 28 Sep 2011 11:21:46 +0200
589fec65c98Schristos  wait!  kristaps@  Sun, 02 Oct 2011 17:12:52 +0200
590fec65c98Schristos
591fec65c98Schristos************************************************************************
592fec65c98Schristos* documentation issues
593fec65c98Schristos************************************************************************
594fec65c98Schristos
595fec65c98Schristos- mention hyphenation rules:
596fec65c98Schristos  breaking at letter-letter in text mode (not macro args)
597fec65c98Schristos  proper hyphenation is unimplemented
598fec65c98Schristos
599fec65c98Schristos- talk about spacing around delimiters
600fec65c98Schristos  to jmc@, kristaps@  Sat, 23 Apr 2011 17:41:27 +0200
601fec65c98Schristos
602fec65c98Schristos- mark macros as: page structure domain, manual domain, general text domain
603fec65c98Schristos  is this useful?
604fec65c98Schristos
605fec65c98Schristos- mention /usr/share/misc/mdoc.template in mdoc(7)?
606fec65c98Schristos
607fec65c98Schristos- Is all the content from http://www.std.com/obi/BSD/doc/usd/28.tbl/tbl
608fec65c98Schristos  covered in tbl(7)?
6090d88b603Schristos
6100d88b603Schristos************************************************************************
6110d88b603Schristos* performance issues
6120d88b603Schristos************************************************************************
6130d88b603Schristos
614fec65c98Schristos- Why are we using MAP_SHARED, not MAP_PRIVATE for mmap(2)?
615fec65c98Schristos  How does SQLITE_CONFIG_PAGECACHE actually work?  Document it!
616fec65c98Schristos  from kristaps@  Sat, 09 Aug 2014 13:51:36 +0200
617fec65c98Schristos
6180d88b603SchristosSeveral areas can be cleaned up to make mandoc even faster.  These are
6190d88b603Schristos
6200d88b603Schristos- improve hashing mechanism for macros (quite important: performance)
6210d88b603Schristos
6220d88b603Schristos- improve hashing mechanism for characters (not as important)
6230d88b603Schristos
6240d88b603Schristos- the PDF file is HUGE: this can be reduced by using relative offsets
6250d88b603Schristos
6260d88b603Schristos- instead of re-initialising the roff predefined-strings set before each
6270d88b603Schristos  parse, create a read-only version the first time and copy it
628fec65c98Schristos  loc *  exist **  algo **  size *  imp **
6290d88b603Schristos
6300d88b603Schristos************************************************************************
6310d88b603Schristos* structural issues
6320d88b603Schristos************************************************************************
6330d88b603Schristos
6340d88b603Schristos- We use the input line number at several places to distinguish
6350d88b603Schristos  same-line from different-line input.  That plainly doesn't work
6360d88b603Schristos  with user-defined macros, leading to random breakage.
6370d88b603Schristos
6380d88b603Schristos- Find better ways to prevent endless loops
6390d88b603Schristos  in roff(7) macro and string expansion.
6400d88b603Schristos
6410d88b603Schristos- Finish cleanup of date handling.
6420d88b603Schristos  Decide which formats should be recognized where.
6430d88b603Schristos  Update both mdoc(7) and man(7) documentation.
6440d88b603Schristos  Triggered by  Tim van der Molen  Tue, 22 Feb 2011 20:30:45 +0100
645fec65c98Schristos
646fec65c98Schristos- struct mparse refactoring
647fec65c98Schristos  Steffen Nurpmeso  Thu, 04 Sep 2014 12:50:00 +0200
648fec65c98Schristos
649fec65c98Schristos- Consider creating some views that will make the database more
650fec65c98Schristos  readable from the sqlite3 shell.  Consider using them to
651fec65c98Schristos  abstract from the database structure, too.
652fec65c98Schristos  suggested by espie@  Sat, 19 Apr 2014 14:52:57 +0200
653fec65c98Schristos
654fec65c98Schristos************************************************************************
655fec65c98Schristos* CGI issues
656fec65c98Schristos************************************************************************
657fec65c98Schristos
658fec65c98Schristos - Enable HTTP compression by detecting gzip encoding and filtering
659fec65c98Schristos   output through libz.
660fec65c98Schristos - Sandbox (see OpenSSH).
661fec65c98Schristos - Enable caching support via HTTP 304 and If-Modified-Since.
662fec65c98Schristos - Allow for cgi.h to be overridden by CGI environment variables.
663fec65c98Schristos   Otherwise, binary distributions will inherit the compile-time
664fec65c98Schristos   behaviour, which is not optimal.
665fec65c98Schristos - Have Mac OSX systems automatically disable -static compilation of the
666fec65c98Schristos   CGI: -static isn't supported.
667fec65c98Schristos
668fec65c98Schristos************************************************************************
669fec65c98Schristos* to improve in the groff_mdoc(7) macros
670fec65c98Schristos************************************************************************
671fec65c98Schristos
672fec65c98Schristos- use uname(1) to set doc-default-operating-system at install time
673fec65c98Schristos  tobimensch  Mon, 1 Dec 2014 00:25:07 +0100
674