mdocml: results of some systematic comparisons

mdocml: results of some systematic comparisons

[schwarze]

Log Message:
-----------
results of some systematic comparisons

Modified Files:
--------------
    mdocml:
        TODO

Revision Data
-------------
Index: TODO
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/TODO,v
retrieving revision 1.82
retrieving revision 1.83
diff -LTODO -LTODO -u -p -r1.82 -r1.83
--- TODO
+++ TODO
@@ -10,6 +10,15 @@
 - .TP before .SH is still FATAL in man(7)
   reported by brad@  Sat, 15 Jan 2011 15:54:54 -0500
 
+- The mdoc(7) parser should handle `\.' as punctuation:
+    .Ql .if ${VAR} op something \.
+  should produce
+    `.if ${VAR} op something'.
+  not
+    `.if ${VAR} op something .'
+  as seen in make(1).
+  To escape the dot, one would use `\&.'.
+
 - the roff parser doesn't tolerate additional characters between
   a macro and the \} terminating a conditional block, e.g.
   .if n \{
@@ -49,6 +58,8 @@
 
 - pod2man expects `tr' to be implemented for \*(-- to work
 
+- \c (interrupted text) occurs in chat(8)
+
 --- missing mdoc features ----------------------------------------------
 
 - fix bad block nesting involving multiple identical explicit blocks
@@ -125,6 +136,14 @@
       see textproc/mgdiff(1) for nice examples
   (3) undefined, just output the character -> perhaps WARNING
 
+- The \t escape sequence is the same as a literal tab, see for example
+  the ASCII table in hexdump(1) where
+    .Bl -column \&000_nu \&001_so \&002_st \&003_et \&004_eo
+    .It \&000\ nul\t001\ soh\t002\ stx\t003\ etx\t004\ eot\t005\ enq
+  produces
+    000 nul  001 soh  002 stx  003 etx  004 eot  005 enq
+  and the example in oldrdist(1)
+
 - 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.
@@ -158,6 +177,15 @@
   try e.g. .Bl -column It Ta Ta
   reported by millert Fri, 02 Apr 2010 16:13:46 -0400
 
+- .%T can have trailing punctuation.  Currently, it puts the trailing
+  punctuation into a trailing MDOC_TEXT element inside its own scope.
+  That element should rather be outside its scope, such that the
+  punctuation does not get underlines.  This is not trivial to
+  implement because .%T then needs some features of in_line_eoln() -
+  slurp all arguments into one single text element - and one feature
+  of in_line() - put trailing punctuation out of scope.
+  Found in mount_nfs(8) and exports(5), search for "Appendix".
+
 - in enclosures, mandoc sometimes fancies a bogus end of sentence
   reminded by jmc@  Thu, 23 Sep 2010 18:13:39 +0059
 
@@ -180,18 +208,42 @@
 
 - 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).
+  or in DIAGNOSTICS in init(8), or before "is always true" in ksh(1).
+  The same happens with .Pp just before .El, see bgpd.conf(5).
   Also have `It' complain if `Pp' is invoked at certain times (not
   -compact?).
 
+- If the *first* line after .It is .Pp, break the line right after
+  the tag, do not pad with space characters before breaking.
+  See the description of the a, c, and i commands in sed(1).
+
+- If the first line after .It is .D1, do not assert a blank line
+  in between, see for example tmux(1).
+  reported by nicm@  13 Jan 2011 00:18:57 +0000
+
 - .Nx 1.0a
   should be "NetBSD 1.0A", not "NetBSD 1.0a",
   see OpenBSD ccdconfig(8).
 
+- The space character joining .Dx .Fx .Nx .Ox (are these all?) to its
+  argument is non-breaking.  See the cdio(1) HISTORY and many others.
+
+- .Bx uses a dash before its argument, not a space,
+  see for example the chpass(1) and column(1) HISTORY.
+  Besides, the second argument is capitalized, for example,
+    .Bx 4.3 tahoe .
+  produces 4.3BSD-Tahoe.
+
 - 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 the -width string contains macros, the macros must be rendered
+  before measuring the width, for example
+    .Bl -tag -width ".Dv message"
+  in magic(5), located in src/usr.bin/file, is the same
+  as -width 7n, not -width 11n.
+
 - 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.
@@ -200,10 +252,51 @@
   should be indented, see e.g. rpc(3);
   reported by jmc@ on discuss@  Fri, 29 Oct 2010 13:48:33 +0100
 
+- .Ns should only be effective when called by another macro,
+  not as a stand-alone macro at the beginning of a line;
+  see for example the awk(1) SYNOPSIS.
+
+- .Ns should work when called at the end of an input line, see
+  the following code in vi(1):
+    .It Xo
+    .Op Ar line
+    .Cm a Ns Op Cm ppend Ns
+    .Op Cm !\&
+    .Xc
+    The input text is appended after the specified line.
+
+- When we have both .%T and .%B in .Rs, .%T uses "", not underline, see
+  for example arp(4); admittedly, arp(4) is abusing both .%T and .%B,
+  but when dealing with anthologies, sensible use of of both in the
+  same .Rs can occur.
+
 - Header lines of excessive length:
   Port OpenBSD man_term.c rev. 1.25 to mdoc_term.c
   and document it in mdoc(7) and man(7) COMPATIBILITY
   found while talking to Chris Bennett
+
+- In man(7), the sequence
+    .HP
+    one line of regular text
+    .SH
+  should not produce two blank lines before the .SH,
+  see for example named-checkconf(8).
+
+- In man(7), the sequence
+    regular text
+    .RS
+    .IP
+  should have a blank line between the text and the beginning of the
+  indented paragraph, see for example sudo(1).
+
+- At least sometimes, .sp is ignored right after .SH; see named.conf(5).
+
+- trailing whitespace must be ignored even when followed by a font escape,
+  see for example 
+    makes
+    \fBdig \fR
+    operate in batch mode
+  in dig(1).
 
 ************************************************************************
 * error reporting issues
--
 To unsubscribe send an email to source+unsubscribe@mdocml.bsd.lv