Re: Where to put mandoc roff documentation?

Re: Where to put mandoc roff documentation?

[Ingo Schwarze]

Hi,

replying to myself in order to hold my promise:

Ingo Schwarze wrote on Sat, Nov 27, 2010 at 10:46:31PM +0100:

> Good, so i shall soon move roff.7 to share/man/man7

Done.

> and start polishing it such that we can install it
> once we feel it is ripe.

Do you think the patch below is sufficient to get it ready
for installing it?

Changes:
 - Change the one-line description to
     "roff language reference for mandoc"
   because what we have is really too presumptuous.
 - A bit more motivation in the DESCRIPTION.
 - Point to mandoc_char(7) below LANGUAGE SYNTAX.
 - Change MACRO SYNTAX to REQUEST SYNTAX.
   In roff, the little things after the initial dot that are built-in
   to the language have always been called "requests".
   In roff, "macros" are only those things defined by the user
   or by macro packages.
   In the same spirit, avoid the repetitive term "user-defined macro",
   but keep "user-defined string", as there are also predefined strings.
 - Describe request syntax more systematically.
   This also allows to remove the remark that arguments are
   delimited by whitespace at one or two other places.
 - Remove bogus backslashes from an `.if' example.
   No idea how they got there.
   I tested that the code works without the backslashes.
 - The braces supported by conditional requests are not macros,
   but escape sequences.
 - Make the documentation of the nS register a bit more precise.
 - Referring to doc.tmac makes no sense in roff(7).
 - Add SEE ALSO and HISTORY.

[...]
> Once we will be installing it, we can then start moving class 1
> stuff there.

That's still for the future.

Yours,
  Ingo


Index: Makefile
===================================================================
RCS file: /cvs/src/share/man/man7/Makefile,v
retrieving revision 1.16
diff -u -r1.16 Makefile
--- Makefile	20 Jul 2010 19:30:18 -0000	1.16
+++ Makefile	28 Nov 2010 14:54:14 -0000
@@ -1,12 +1,13 @@
 #	$OpenBSD: Makefile,v 1.16 2010/07/20 19:30:18 schwarze Exp $
 #	$NetBSD: Makefile,v 1.6 1994/12/22 10:50:05 cgd Exp $
 
-# missing: eqnchar.7 ms.7 term.7
+# missing: term.7
 
 MAN=	ascii.7 environ.7 glob.7 hier.7 hostname.7 intro.7 kgdb.7 \
 	library-specs.7 mailaddr.7 \
 	man.7 mandoc_char.7 mdoc.7 mdoc.samples.7 mirroring-ports.7 \
-	operator.7 packages.7 packages-specs.7 ports.7 script.7 securelevel.7
+	operator.7 packages.7 packages-specs.7 ports.7 roff.7 \
+	script.7 securelevel.7
 MLINKS=	mdoc.7 mandoc.7 mdoc.samples.7 mandoc.samples.7 \
 	mirroring-ports.7 mirror-maker.7
 
Index: roff.7
===================================================================
RCS file: /cvs/src/share/man/man7/roff.7,v
retrieving revision 1.2
diff -u -r1.2 roff.7
--- roff.7	28 Nov 2010 01:00:41 -0000	1.2
+++ roff.7	28 Nov 2010 14:54:14 -0000
@@ -20,59 +20,78 @@
 .Os
 .Sh NAME
 .Nm roff
-.Nd roff language reference
+.Nd roff language reference for mandoc
 .Sh DESCRIPTION
 The
 .Nm roff
-language is a general-purpose text-formatting language.  The purpose of
-this document is to consistently describe those language constructs
-accepted by the
+language is a general-purpose text-formatting language.
+In particular, it serves as the basis for the
+.Xr mdoc 7
+and
+.Xr man 7
+manual formatting macro languages.
+This manual describes the subset of the
+.Nm
+language accepted by the
 .Xr mandoc 1
-utility.  It is a work in progress.
+utility.
 .Pp
-An
-.Nm
-document follows simple rules:  lines beginning with the control
-characters
+Input lines beginning with the control characters
 .Sq \.
 or
 .Sq \(aq
 are parsed for requests and macros.
-Other lines are interpreted within the scope of
-prior macros:
-.Bd -literal -offset indent
-\&.xx Macro lines change control state.
-Other lines are interpreted within the current state.
-.Ed
+These define the document structure, change the processing state
+and manipulate the formatting.  Some requests and macros also
+produce formatted output, while others do not.
+.Pp
+All other input lines provide free-form text to be printed;
+the formatting of free-form text depends on the respective
+processing context.
 .Sh LANGUAGE SYNTAX
 .Nm
 documents may contain only graphable 7-bit ASCII characters, the space
-character, and, in certain circumstances, the tab character.  All
-manuals must have
+character, and, in certain circumstances, the tab character.
+To produce other characters in the output, use the escape sequences
+documented in the
+.Xr mandoc_char 7
+manual.
+.Pp
+All manuals must have
 .Ux
 line terminators.
-.Sh MACRO SYNTAX
-Requests and macros are arbitrary in length and begin with a control
-character,
+.Sh REQUEST SYNTAX
+A request or macro line consists of
+.Bl -enum -compact
+.It
+the control character
 .Sq \.
 or
-.Sq \(aq ,
-at the beginning of the line.
-An arbitrary amount of whitespace may sit between the control character
-and the request or macro name.
-Thus, the following are equivalent:
+.Sq \(aq
+at the beginning of the line,
+.It
+optionally an arbitrary amount of whitespace,
+.It
+the name of the request or the macro, which is one word of arbitrary
+length, terminated by whitespace,
+.It
+and zero or more arguments delimited by whitespace.
+.El
+.Pp
+Thus, the following request lines are all equivalent:
 .Bd -literal -offset indent
-\&.if
-\&.\ \ \ \&if
+\&.ig end
+\&.ig    end
+\&.   ig end
 .Ed
 .Sh REQUEST REFERENCE
-This section is a canonical reference of all requests recognized by the
+The
 .Xr mandoc 1
 .Nm
-parser.
-The
+parser recognizes the following requests.
+Note that the
 .Nm
-language defines many more requests and macros not implemented in
+language defines many more requests not implemented in
 .Xr mandoc 1 .
 .Ss \&ad
 Set line adjustment mode.
@@ -103,7 +122,7 @@
 .Xr mandoc 1 ,
 as are its children.
 .Ss \&de
-Define a user-defined
+Define a
 .Nm
 macro.
 Its syntax can be either
@@ -149,7 +168,7 @@
 .Nm
 macro, but not as a high-level macro.
 .Pp
-A user-defined macro can be invoked later using the syntax
+The macro can be invoked later using the syntax
 .Pp
 .D1 Pf . Ar name Op Ar argument Op Ar argument ...
 .Pp
@@ -160,12 +179,12 @@
 To include the double-quote character into a quoted argument,
 escape it from ending the argument by doubling it.
 .Pp
-The line invoking the user-defined macro will be replaced
+The line invoking the macro will be replaced
 in the input stream by the
 .Ar macro definition ,
 replacing all occurrences of
 .No \e\e$ Ns Ar N ,
-where 
+where
 .Ar N
 is a digit, by the
 .Ar N Ns th Ar argument .
@@ -183,7 +202,7 @@
 .Pp
 in the input stream, and thus in the output: \fI\^XtFree\^\fP.
 .Pp
-Since user-defined macros and strings share a common string table,
+Since macros and user-defined strings share a common string table,
 defining a macro
 .Ar name
 clobbers the user-defined string
@@ -197,16 +216,16 @@
 but this is rarely useful because every macro definition contains at least
 one explicit newline character.
 .Ss \&dei
-Define a user-defined
+Define a
 .Nm
 macro, specifying the macro name indirectly.
-The syntax of this macro is the same as that of
+The syntax of this request is the same as that of
 .Sx \&de .
 It is currently ignored by
 .Xr mandoc 1 ,
 as are its children.
 .Ss \&de1
-Define a user-defined
+Define a
 .Nm
 macro that will be executed with
 .Nm
@@ -218,7 +237,7 @@
 .Xr mandoc 1
 does not implement
 .Nm
-compatibility mode at all, it handles this macro as an alias for
+compatibility mode at all, it handles this request as an alias for
 .Sx \&de .
 .Ss \&ds
 Define a user-defined string.
@@ -252,7 +271,7 @@
 Since user-defined strings and macros share a common string table,
 defining a string
 .Ar name
-clobbers the user-defined macro
+clobbers the macro
 .Ar name ,
 and the
 .Ar name
@@ -286,7 +305,7 @@
 .Sx \&ie
 calls)
 then false is assumed.
-The syntax of this macro is similar to
+The syntax of this request is similar to
 .Sx \&if
 except that the conditional is missing.
 .Ss \&hy
@@ -317,19 +336,19 @@
 document.
 Thus,
 .Pp
-.D1 \&.if t \e .ig
+.D1 \&.if t .ig
 .Pp
 will discard the
 .Sq \&.ig ,
 which may lead to interesting results, but
 .Pp
-.D1 \&.if t \e .if t \e{\e
+.D1 \&.if t .if t \e{\e
 .Pp
 will continue to syntactically interpret to the block close of the final
 conditional.
 Sub-conditionals, in this case, obviously inherit the truth value of
 the parent.
-This macro has the following syntax:
+This request has the following syntax:
 .Pp
 .Bd -literal -offset indent -compact
 \&.if COND \e{\e
@@ -366,12 +385,12 @@
 .Pp
 If the BODY section is begun by an escaped brace
 .Sq \e{ ,
-scope continues until a closing-brace macro
+scope continues until a closing-brace escape sequence
 .Sq \.\e} .
-If the BODY is not enclosed in braces, scope continues until the next
-macro or word.
+If the BODY is not enclosed in braces, scope continues until
+the end of the line.
 If the COND is followed by a BODY on the same line, whether after a
-brace or not, then macros
+brace or not, then requests and macros
 .Em must
 begin with a control character.
 It is generally more intuitive, in this case, to write
@@ -382,20 +401,20 @@
 \&.\e}
 .Ed
 .Pp
-than having the macro follow as
+than having the request or macro follow as
 .Pp
 .D1 \&.if COND \e{ .foo
 .Pp
 The scope of a conditional is always parsed, but only executed if the
 conditional evaluates to true.
 .Pp
-Note that text subsequent a
+Note that text following an
 .Sq \&.\e}
-macro is discarded.
+escape sequence is discarded.
 Furthermore, if an explicit closing sequence
 .Sq \e}
 is specified in a free-form line, the entire line is accepted within the
-scope of the prior macro, not only the text preceding the close, with the
+scope of the prior request, not only the text preceding the close, with the
 .Sq \e}
 collapsing into a zero-width space.
 .Ss \&ig
@@ -416,7 +435,7 @@
 .Pp
 In the first case, input is ignored until a
 .Sq \&..
-macro is encountered on its own line.
+request is encountered on its own line.
 In the second case, input is ignored until the specified
 .Sq Pf . Ar end
 macro is encountered.
@@ -441,7 +460,7 @@
 .Ar ignored text ,
 and arguments following it or the
 .Sq \&..
-macro are discarded.
+request are discarded.
 .Ss \&ne
 Declare the need for the specified minimum vertical space
 before the next trap or the bottom of the page.
@@ -466,9 +485,6 @@
 The
 .Ar value
 may, at the moment, only be an integer.
-The
-.Ar name
-is defined up to the next whitespace.
 So far, only the following register
 .Ar name
 is recognised:
@@ -476,15 +492,19 @@
 .It Cm nS
 If set to a positive integer value, certain
 .Xr mdoc 7
-macros will behave as if they were defined in the
+macros will behave in the same way as in the
 .Em SYNOPSIS
 section.
-Otherwise, this behaviour is unset (even if called within the
+If set to 0, these macros will behave in the same way as outside the
 .Em SYNOPSIS
-section itself).
-Note that invoking a new
+section, even when called within the
+.Em SYNOPSIS
+section itself.
+Note that starting a new
 .Xr mdoc 7
-section will unset this value.
+section with the
+.Cm Sh
+macro will reset this register.
 .El
 .Ss \&so
 Include a source file.
@@ -505,39 +525,69 @@
 .Qq /.. .
 .Ss \&tr
 Output character translation.
-This macro is intended to have one argument,
+This request is intended to have one argument,
 consisting of an even number of characters.
 Currently, it is ignored including its arguments,
 and the number of arguments is not checked.
 .Sh COMPATIBILITY
 This section documents compatibility between mandoc and other other
-troff implementations, at this time limited to GNU troff
+.Nm
+implementations, at this time limited to GNU troff
 .Pq Qq groff .
 The term
 .Qq historic groff
-refers to groff versions before the
-.Pa doc.tmac
-file re-write
-.Pq somewhere between 1.15 and 1.19 .
+refers to groff version 1.15.
 .Pp
 .Bl -dash -compact
 .It
 The
 .Cm nS
-request to
-.Sx \&nr
-is only compatible with OpenBSD's groff.
+register is only compatible with OpenBSD's groff-1.15.
 .It
-Historic groff did not accept white-space buffering the custom END tag
-for the
+Historic groff did not accept white-space before a custom
+.Ar end
+macro for the
 .Sx \&ig
-macro.
+request.
 .It
 The
 .Sx \&if
 and family would print funny white-spaces with historic groff when
-depending on next-line syntax.
+using the next-line syntax.
 .El
+.Sh SEE ALSO
+.Xr mandoc 1 ,
+.Xr man 7 ,
+.Xr mandoc_char 7 ,
+.Xr mdoc 7
+.Rs
+.%A Joseph F. Ossanna
+.%A Brian W. Kernighan
+.%I AT&T Bell Laboratories
+.%T Troff User's Manual
+.%R Computing Science Technical Report
+.%N 54
+.%C Murray Hill, New Jersey
+.%D 1976 and 1992
+.%U http://www.kohala.com/start/troff/cstr54.ps
+.Re
+.Rs
+.%A Joseph F. Ossanna
+.%A Brian W. Kernighan
+.%A Gunnar Ritter
+.%T Heirloom Documentation Tools Nroff/Troff User's Manual
+.%D September 17, 2007
+.%U http://heirloom.sourceforge.net/doctools/troff.pdf
+.Re
+.Sh HISTORY
+The RUNOFF typesetting system was written in PL/1 for the CTSS
+operating system by Jerome ("Jerry") E. Saltzer in 1961.
+It was first used as the main documentation tool by Multics since 1963.
+Robert ("Bob") H. Morris ported it to the GE-635 and called it
+.Nm ,
+Doug McIlroy rewrote it in BCPL in 1969,
+Joseph F. Ossanna rewrote it in PDP-11 assembly in 1973,
+and Brian W. Kernighan rewrote it in C in 1975.
 .Sh AUTHORS
 .An -nosplit
 This partial
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

Re: Where to put mandoc roff documentation?

[Kristaps Dzonsons]

> replying to myself in order to hold my promise:
>
> Ingo Schwarze wrote on Sat, Nov 27, 2010 at 10:46:31PM +0100:
>
>> Good, so i shall soon move roff.7 to share/man/man7
>
> Done.
>
>> and start polishing it such that we can install it
>> once we feel it is ripe.
>
> Do you think the patch below is sufficient to get it ready
> for installing it?
>
> Changes:
>   - Change the one-line description to
>       "roff language reference for mandoc"
>     because what we have is really too presumptuous.
>   - A bit more motivation in the DESCRIPTION.
>   - Point to mandoc_char(7) below LANGUAGE SYNTAX.
>   - Change MACRO SYNTAX to REQUEST SYNTAX.
>     In roff, the little things after the initial dot that are built-in
>     to the language have always been called "requests".
>     In roff, "macros" are only those things defined by the user
>     or by macro packages.
>     In the same spirit, avoid the repetitive term "user-defined macro",
>     but keep "user-defined string", as there are also predefined strings.
>   - Describe request syntax more systematically.
>     This also allows to remove the remark that arguments are
>     delimited by whitespace at one or two other places.
>   - Remove bogus backslashes from an `.if' example.
>     No idea how they got there.
>     I tested that the code works without the backslashes.
>   - The braces supported by conditional requests are not macros,
>     but escape sequences.
>   - Make the documentation of the nS register a bit more precise.
>   - Referring to doc.tmac makes no sense in roff(7).
>   - Add SEE ALSO and HISTORY.
>
> [...]
>> Once we will be installing it, we can then start moving class 1
>> stuff there.
>
> That's still for the future.

Ingo and Jason,

I, for one, have no issues with these changes.  Feel free to commit them 
into BSD.lv.

Thanks!

Kristaps
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

Re: Where to put mandoc roff documentation?

[Ingo Schwarze]

Hi Kristaps,

Kristaps Dzonsons wrote on Mon, Nov 29, 2010 at 06:01:16PM +0100:

> I, for one, have no issues with these changes.

Good, they are now in OpenBSD, and we now install roff(7).
Thanks for your review, Jason!

> Feel free to commit them into BSD.lv.

I'd like to, but that path is blocked for now.
Kristaps, you are lacking lots of features!
Look at this:

revision 1.9
date: 2010/11/27 02:17:43;  author: schwarze;  state: Exp;  lines: +19 -2
Document .so.
This file still needs lots of love before we can consider installing it.
----------------------------
revision 1.10
date: 2010/11/27 17:46:46;  author: schwarze;  state: Exp;  lines: +240 -85
Document .de and .de1.
Extend and improve .ds documentation.
Improve .ig and .nr documentation.
Add minimal explanations for .am, .ami, .am1, and .dei.
Start improving the distinction of requests and macros.
Add myself as an author.
----------------------------
revision 1.2
date: 2010/11/28 01:00:41;  author: schwarze;  state: Exp;  lines: +17 -1
Parse and ignore the .ad, .hy, .nh, and .ne roff requests.
Ignoring these can neither cause information loss nor serious
formatting issues.  As they are frequently used by pod2man(1),
this considerably reduces ERROR noise from mandoc -Tlint
for the Perl manuals.
----------------------------
revision 1.3
date: 2010/11/29 00:12:02;  author: schwarze;  state: Exp;  lines: +30 -2
Implement the roff .ft (change font) request for man(7).
Of course, we don't want to encourage low-level physical markup,
but pod2man(1) writes such requests, so Perl manuals contain them,
and some Xenocara and lots and lots of ports manuals use them as well.
In base and Xenocara, this will reduce mandoc -Tlint ERROR noise;
in ports, it will improve rendering of many manuals.

Of course, none of this can go into bsd.lv right now,
or you badly get your code and docs out of sync.

Trying to apply just the cleanup diff blows up pathetically:

Patching file roff.7 using Plan A...
Hunk #1 failed at 15.
Hunk #2 failed at 123.
Hunk #3 failed at 169.
Hunk #4 failed at 180.
Hunk #5 failed at 203.
Hunk #6 failed at 217.
Hunk #7 failed at 238.
Hunk #8 failed at 272.
Hunk #9 succeeded at 151 with fuzz 1 (offset -155 lines).
Hunk #10 succeeded at 334 (offset -31 lines).
No such line 362 in input file, ignoring
Hunk #11 succeeded at 259 (offset -155 lines).
Hunk #12 succeeded at 399 (offset -31 lines).
Hunk #13 failed at 433.
Hunk #14 failed at 458.
Hunk #15 failed at 483.
Hunk #16 succeeded at 356 with fuzz 2 (offset -165 lines).
Hunk #17 succeeded at 506 with fuzz 2 (offset -48 lines).
11 out of 17 hunks failed--saving rejects to roff.7.rej
done

Look at the offsets, it's not even patching the right parts
of the file for those few chunks that don't conflict.

So sorry...

Yours,
  Ingo
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv