~sircmpwn/public-inbox

General catch-all for patches, questions, and discussions for sircmpwn's projects that don't have their own mailing list.

When posting patches to this list, please edit the [PATCH] line to include the specific project you're contributing to, e.g.

[PATCH scdoc v2] Add thing to stuff

Patches

1 2

[PATCH] Omit needless words, change description to UNIX/BSD style.

Details
Message ID
<20181119144231.13069-1-themanhimself@sgregoratto.me>
Download raw message
Patch +5 -7
	Regardless of standards considerations, if there's any advice
	that needs to be hammered into man authors, it's to be concise
	and accurate, but not pedantic. As Will Strunk commanded,
	"Omit needless words."

	The most needless words of all are promotional. No man page
	should utter words like "powerful", "extraordinarily versatile",
	"user-friendly", or "has a wide range of options".

	-- Doug McIlroy[1]
	[1] https://lists.gnu.org/archive/html/groff/2018-11/msg00058.html
---
 scdoc.1.scd | 10 ++++------
 scdoc.5.scd |  2 +-
 2 files changed, 5 insertions(+), 7 deletions(-)

diff --git a/scdoc.1.scd b/scdoc.1.scd
index 4153c10..74c38d2 100644
--- a/scdoc.1.scd
+++ b/scdoc.1.scd
@@ -2,18 +2,16 @@ scdoc(1)
 
 # NAME
 
-scdoc - tool for generating *roff*(7) manual pages
+scdoc - generate *man*(7) manual pages
 
 # SYNOPSIS
 
-*scdoc* < _input_ > _output_
+*scdoc* < _input_
 
 # DESCRIPTION
 
-scdoc is a tool designed to make the process of writing man pages more
-friendly. It reads scdoc syntax from stdin and writes roff to stdout, suitable
-for reading with *man*(1). For a description of the syntax of scdoc source
-files, see *scdoc*(5).
+The scdoc utility reads *scdoc*(5) syntax from the standard input and writes
+*man*(7) style roff to the standard output.
 
 # SEE ALSO
 
diff --git a/scdoc.5.scd b/scdoc.5.scd
index dfe5353..42c1ec0 100644
--- a/scdoc.5.scd
+++ b/scdoc.5.scd
@@ -14,7 +14,7 @@ Each scdoc file must begin with the following preamble:
 
 	*name*(_section_) ["left\_footer" ["center\_header"]]
 
-The *name* is the name of the man page you are writing, and _section_ is the
+*name* is the name of the man page you are writing, and _section_ is the
 section you're writing for (see *man*(1) for information on manual sections).
 
 _left\_footer_ and _center\_header_ are optional arguments which set the text
-- 
2.19.1
Details
Message ID
<20181119222312.GA4629@homura.localdomain>
In-Reply-To
<20181119144231.13069-1-themanhimself@sgregoratto.me> (view parent)
Download raw message
This is a good patch and I was happy to apply it, but in the future you
should be less abrasive in your approach.

Thanks!

To git.sr.ht:~sircmpwn/scdoc
   56b882d..05ca9f2  master -> master