internal update

3 files changed, 129 insertions, 35 deletions

diff --git a/tmac/doc-common.new b/tmac/doc-common.new
index 47732b1b..958140ce 100755
--- a/tmac/doc-common.new
+++ b/tmac/doc-common.new
@@ -669,6 +669,17 @@
 .nr doc-in-authors-section 0
 .
 .
+.\" NS doc-first-parameter macro
+.\" NS   return first parameter
+.\" NS
+.\" NS local variables:
+.\" NS   doc-str-dfp
+.
+.de doc-first-parameter
+.  ds doc-str-dfp "\$1
+..
+.
+.
 .\" NS Sh user macro (not callable)
 .\" NS   section headers
 .\" NS
@@ -728,7 +739,10 @@
 .      if t \
 '        ad
 .
-.      ie "\$1"\*[doc-section-name]" \{\
+.      \" this resolves e.g. `.Sh "SEE ALSO"'
+.      doc-first-parameter \$*
+.
+.      ie "\*[doc-str-dfp]"\*[doc-section-name]" \{\
 .        doc-setup-header
 '        in 0
 .      \}
@@ -737,25 +751,25 @@
 .        nr doc-in-files-section 0
 .        nr doc-in-authors-section 0
 .
-.        ie        "\$1"\*[doc-section-synopsis]" \{\
+.        ie        "\*[doc-str-dfp]"\*[doc-section-synopsis]" \{\
 .          if t \
 .            na
 .          nr doc-in-synopsis-count 1
 .        \}
-.        el \{ .ie "\$1"\*[doc-section-description]" \{\
+.        el \{ .ie "\*[doc-str-dfp]"\*[doc-section-description]" \{\
 .          nr doc-is-func 0
 .          nr doc-func-count 0
 .          nr doc-func-args-processed 0
 .          nr doc-num-func-args 0
 .        \}
-.        el \{ .ie "\$1"\*[doc-section-see-also]" \{\
+.        el \{ .ie "\*[doc-str-dfp]"\*[doc-section-see-also]" \{\
 .          if t \
 .            na
 .          nr doc-in-see-also-section 1
 .        \}
-.        el \{ .ie "\$1"\*[doc-section-files]" \
+.        el \{ .ie "\*[doc-str-dfp]"\*[doc-section-files]" \
 .          nr doc-in-files-section 1
-.        el .if    "\$1"\*[doc-section-authors]" \
+.        el .if    "\*[doc-str-dfp]"\*[doc-section-authors]" \
 .          nr doc-in-authors-section 1
 .        \}\}\}
 .
diff --git a/tmac/groff_mdoc.reference.man b/tmac/groff_mdoc.reference.man
index aea76027..1ce83b36 100755
--- a/tmac/groff_mdoc.reference.man
+++ b/tmac/groff_mdoc.reference.man
@@ -204,6 +204,7 @@ as follows:
 .
 .  Bl -tag -width 2n -compact
 .    It "Section Headers"
+.    It "Subsection Headers"
 .    It "Paragraphs and Line Spacing"
 .    It "Keeps"
 .    It "Examples and Displays"
@@ -615,9 +616,9 @@ and
 .Sx DESCRIPTION
 are mandatory.
 The headers are discussed in
-.Sx PAGE STRUCTURE DOMAIN ,
+.Sx "PAGE STRUCTURE DOMAIN" ,
 after presentation of
-.Sx MANUAL DOMAIN .
+.Sx "MANUAL DOMAIN" .
 Several content macros are used to demonstrate page layout macros; reading
 about content macros before page layout macros is recommended.
 .
@@ -1365,7 +1366,9 @@ The default width is 12n.
 .
 The 
 .Ql .Fn
-macro is modeled on ANSI C conventions.
+macro is modeled on
+.Tn ANSI\~C
+conventions.
 .Pp
 .Dl Usage: .Fn Ao function Ac Oo Ao parameter Ac Oc Ld
 .Pp
@@ -2046,6 +2049,14 @@ have a default width value of 12n.
 .It Li .Ec , .Eo
 These macros expect the first argument to be the opening and closing strings
 respectively.
+.It Li .Es , .En
+Due to the nine-argument limit in the original troff program two other
+macros have been implemented which are now rather obsolete:
+.Ql .Es
+takes the first and second parameter as the left and right enclosure string,
+which are then used to enclose the arguments of
+.Ql .En .
+The default width value is 12n for both macros.
 .It Li .Eq
 The first and second argument of this macro are the opening resp.\& the
 closing string (followed by the arguments to be enclosed).
@@ -2555,7 +2566,7 @@ section.
 .It Li ".Sh SEE ALSO"
 References to other material on the man page topic and cross references to
 other relevant man pages should be placed in the
-.Sx SEE ALSO
+.Sx "SEE ALSO"
 section.
 Cross references are specified using the
 .Ql .Xr
@@ -2609,9 +2620,21 @@ User-specified
 sections may be added; for example, this section was set with:
 .
 .Bd -literal -offset 15n
-\&.Sh PAGE STRUCTURE DOMAIN
+\&.Sh "PAGE STRUCTURE DOMAIN"
 .Ed
 .
+.Ss "Subsection Headers"
+.
+Subsection headers have exactly the same syntax as section headers:
+.Ql .Ss
+is parsed but not generally callable.
+It can be used as an argument in a call to
+.Ql .Ss
+only; it then reactivates the default font for
+.Ql .Ss .
+.Pp
+The default width is 8n.
+.
 .Ss "Paragraphs and Line Spacing"
 .
 .Bl -tag -xwidth ".Li .Pp"
@@ -3483,6 +3506,15 @@ Suppress insertion of vertical space before the list and between list items.
 \#
 .Sh "MISCELLANEOUS MACROS"
 .
+Here a list of the remaining macros which don't fit well into one of the
+above sections.
+We couldn't find real examples for the following macros:
+.Ql .Vt
+They are documented here for completeness \- if you know how to use them
+properly please send a mail to
+.Mt bug-groff@gnu.org
+(including an example).
+.
 .Bl -tag -xwidth ".Li .Bt"
 .It Li .Bt
 prints
@@ -3491,7 +3523,44 @@ prints
 .Bt
 .Ed
 .Pp
-It is neither callable no parsable and takes no arguments.
+It is neither callable nor parsable and takes no arguments.
+.
+.It Li .Fr
+.Pp
+.Dl Usage: .Fr Ao function return value Ac Ld
+.Pp
+Don't use this macro.
+It allows a break right before the return value (usually a single digit)
+which is bad typographical behaviour.
+Use
+.Ql \e~
+to tie the return value to the previous word.
+.
+.It Li .Hf
+Use this macro to include a (header) file literally.
+It first prints
+.Ql File:
+followed by the file name, then the contents of
+.Ao file Ac .
+.Pp
+.Dl Usage: .Hf Ao file Ac
+.Pp
+It is neither callable nor parsable.
+.
+.It Li .In
+Specify C\~header file as being called in a C\~program.
+.Pp
+.Dl Usage: .In Ao header file Ac
+.Pp
+This function causes a break.
+For example, the line
+.Pp
+.In stdio.h
+.Pp
+is produced by
+.Ql ".In stdio.h" .
+.Pp
+It is neither callable nor parsable.
 .
 .It Li .Ld
 This macro is similar to TeX's \eldots command; it prints
@@ -3504,7 +3573,14 @@ prints
 .Ud
 .Ed
 .Pp
-It is neither callable no parsable and takes no arguments.
+It is neither callable nor parsable and takes no arguments.
+.
+.It Li .Vt
+Exact usage unknown.
+The spare documentation in the
+.Nm \-mdoc
+source file describes it as
+.Dq "variable type (for forcing old style variable declarations)" .
 .El
 .
 .
diff --git a/tmac/tmac.doc.new b/tmac/tmac.doc.new
index 635410df..7b53bb56 100755
--- a/tmac/tmac.doc.new
+++ b/tmac/tmac.doc.new
@@ -967,39 +967,39 @@
 .\" NS width register `Fd' set in doc-common
 .
 .de Fd
-.  ie \n[doc-arg-limit] \{\
-.    tm Usage: .Fd function_declaration -- Fd is not callable (#\n[.c])
-.    doc-reset-args
-.  \}
-.  el \{\
+.  ie ((\n[.$] >= 1) & (\n[doc-arg-limit] == 0)) \{\
 .    doc-do-func-decl
 .    nop \*[doc-Fd-font]\$*
 .    br
 .    ft \n[doc-curr-font]
 .    ps \n[doc-curr-size]u
 .  \}
+.  el \{\
+.    tm Usage: .Fd function_declaration -- Fd is not callable (#\n[.c])
+.    doc-reset-args
+.  \}
 ..
 .
 .
 .\" NS In user macro
-.\" NS   #include statement - not callable (& no err check)
+.\" NS   #include statement - not callable
 .\" NS
 .\" NS   this function causes a break; it uses the `Fd' font
 .\" NS
 .\" NS width register `In' set in doc-common
 .
 .de In
-.  ie \n[doc-arg-limit] \{\
-.    tm Usage: .In #include_statement -- In is not callable (#\n[.c])
-.    doc-reset-args
-.  \}
-.  el \{\
+.  ie ((\n[.$] == 1) & (\n[doc-arg-limit] == 0)) \{\
 .    doc-do-func-decl
 .    nop \*[doc-Fd-font]#include <\$1>
 .    br
 .    ft \n[doc-curr-font]
 .    ps \n[doc-curr-size]u
 .  \}
+.  el \{\
+.    tm Usage: .In include_file -- In is not callable (#\n[.c])
+.    doc-reset-args
+.  \}
 ..
 .
 .
@@ -1502,8 +1502,8 @@
 .de Es
 .  if !\n[doc-arg-limit] \{\
 .    ie (\n[.$] > 2) \{\
-.        ds doc-macro-name Es
-.        doc-parse-args \$@
+.      ds doc-macro-name Es
+.      doc-parse-args \$@
 .    \}
 .    el \{\
 .      ds doc-quote-left "\$1
@@ -4435,8 +4435,8 @@
 .      doc-reset-args
 .  \}
 .  el \{\
-.    tm1 "Usage: Ta must follow column entry: e.g. (#\n[.c])
-.    tm1 "         .It column_string [Ta [column_string ...]]
+.    tm1 "Usage: Ta must follow column entry: e.g.
+.    tm1 "         .It column_string [Ta [column_string ...]] (#\n[.c])
 .  \}
 ..
 .
@@ -6181,15 +6181,19 @@
 .\" NS width register `Hf' set in doc-common
 .
 .de Hf
-.  doc-paragraph
-.  nop File:
-.  Pa \$1
+.  ie ((\n[.$] == 1) & (\n[doc-arg-limit] == 0)) \{\
+.    doc-paragraph
+.    nop File:
+.    Pa \$1
 .
-.  Bd -literal
-.  so \$1
-.  Ed
+.    Bd -literal
+.    so \$1
+.    Ed
 .
-.  doc-paragraph
+.    doc-paragraph
+.  \}
+.  el \
+.    Usage: .Hf file (#\n[.c])
 ..
 .
 .