Update of bug #59826 (project groff):
Item Group: Incorrect behaviour => Documentation
Status: None => In Progress
Assigned to: None => gbranden
_______________________________________________________
Follow-up Comment #1:
I've decided to treat this as a documentation issue.
Having nroff and troff modes work differently in this respect is, I think,
more likely to be annoying to new users as well as existing groff users, from
whom we've heard few if any complaints on this subject over the past 30
years.
Our documentation was inaccurate on this point, describing AT&T ms behavior,
but I fixed it on 20 March to be accurate. See the "<DA>" item below.
The discrepancy, however, could still be usefully called out in the
"Differences from AT&T ms" section of the manuals, for those users accustomed
to Unix and Heirloom Doctools. So I'll do that.
commit 5be3f4fce7f47ca2a9296b7d48fd16a0ebb40648
Author: G. Branden Robinson <g.branden.robin...@gmail.com>
Date: Sat Mar 20 20:13:02 2021 +1100
[ms]: Revise documentation of cover page macros.
* doc/groff.texi (ms Document Structure):
- Say that macros are "called", not "invoked", for consistency with
other documentation.
- Stop providing mnemonic for RP macro here, since it has two
different ones.
- Loosen claim: .RP does not have to be the first line of an input
document; it simply needs to be early.
- More carefully distinguish between what groff (or troff) does and
what the macro package does.
- Say "document description" instead of "cover page [information]"--a
cover page is only present if .RP is called.
- Be more clear that multiple authors can be declared with .AU.
- Be more clear that the arguments to .DA or .ND need not be a date.
- Refer to the "body" of the text additionally as the "main matter",
since we also must cope with the subjects of tables of contents and
indices.
(ms Cover Page Macros):
- Rename node/section to "ms Document Description Macros". Update
node structure accordingly.
- Add motivating paragraph to introduce section.
- Clarify ordering & presence restrictions on cover page macro calls.
- Describe macros using imperative mood instead of sentence fragments.
- Describe diversion-creating macros in a way that suggests their
operation (without using the technical term).
- Be more clear about what macro calls terminate these diversions.
- Say "cover page" instead of "title page".
- Be specific that the document "date" (DA/ND arguments) appear on a
cover page but not otherwise prior to the main matter.
- <RP> Be more specific about default placement of cover page
information.
- <RP> Note AT&T expansion of macro name.
- <P1> Document as Berkeley Unix extension. Note existence of
conflicting V10 Unix macro.
- <AU> Replace example of multiple authors with explanatory prose.
- <AI> Clarify behavior when called multiple times.
- <DA> Give argument(s) a metasyntactic variable instead of merely an
ellipsis.
- <DA> Undocument this as the "nroff default". GNU ms does not work
this way.
- <ND> Make synopsis consistent with DA since it treats its arguments
the same way.
- Use more idiomatic input in the example.
* doc/ms.ms:
- Add empty request macro between sentences.
- Add two empty request macros where vertical space is expected.
- Synchronize language with our Texinfo manual.
(General structure of an -ms document):
- Convert colon-terminated sentence fragment to a complete sentence.
(Cover page macros):
- Rename section to "Document description macros". Update references.
* tmac/groff_ms.7.man:
- Synchronize language with doc/ms.ms, omitting new motivational
paragraph since this man page will ultimately become a relatively
terse reference document.
_______________________________________________________
Reply to this item at:
<https://savannah.gnu.org/bugs/?59826>
_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
