Bug 229571 - lam(1) man-page doesn't document -S
Summary: lam(1) man-page doesn't document -S
Status: Closed FIXED
Alias: None
Product: Documentation
Classification: Unclassified
Component: Manual Pages (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Some People
Assignee: freebsd-bugs (Nobody)
URL:
Keywords: patch
Depends on:
Blocks:
 
Reported: 2018-07-06 19:12 UTC by Tim Chase
Modified: 2019-03-06 01:27 UTC (History)
3 users (show)

See Also:


Attachments
Document the -S option for lam(1) (943 bytes, patch)
2018-07-06 19:12 UTC, Tim Chase
no flags Details | Diff
Document each capitalized option (1.91 KB, patch)
2018-07-08 20:47 UTC, Tim Chase
no flags Details | Diff

Note You need to log in before you can comment on or make changes to this bug.
Description Tim Chase 2018-07-06 19:12:00 UTC
Created attachment 194921 [details]
Document the -S option for lam(1)

The man page for lam(1) documents "-s" but not "-S" however it uses "-S" in the EXAMPLES section.  The attached patch provides some documentation for "-S".

(sorry if it needs "patch -p N" for an appropriate value of N to apply in the right way)
Comment 1 Rodrigo Osorio freebsd_committer 2018-07-06 20:04:39 UTC
@Tim, I'm sorry but seems that the man page describes clearly what the
-S does, as for the -F -P and -T.

The manpage says :

Normally, each option affects only the file after it.  If the option
letter is capitalized it affects all subsequent files until it appears
again uncapitalized.  The options are described below
Comment 2 Allan Jude freebsd_committer 2018-07-07 01:28:15 UTC
I would work is more specifically, that it affects all inputs that follow, until another -s, and add the uppercase of each other option that is supported as well.
Comment 3 Tim Chase 2018-07-07 02:30:34 UTC
The main issue that triggered this is the common pattern of encountering an unknown option, issuing

  man lam

and then doing a

  /-S

to learn more about the unknown option.  In the case of "-S", it pops to the EXAMPLES section but doesn't land in the DESCRIPTION section.  However, for something like "-T", it's a valid option but never appears in the man-page at all.  Perhaps a better solution would include the upper-case options in the text, something like

  "Normally, each option affects only the file after it.
  If the option letter is capitalized (-F, -P, -S, or -T) it
  affects all subsequent files until it appears again uncapitalized"

to give appropriate search targets?
Comment 4 Allan Jude freebsd_committer 2018-07-07 04:00:45 UTC
(In reply to Tim Chase from comment #3)
I think it makes the most sense to expand them fully, as if we were writing the man page for the first time. Have each of the uppercase options spelled out explicitly, and possibly remove the old text about uppercase (although it seems useful to reinforce the pattern)
Comment 5 Tim Chase 2018-07-08 20:47:31 UTC
Created attachment 194963 [details]
Document each capitalized option

(In reply to Allan Jude from comment #4)

This patch removes the top section (it was awkward to have both) and instead describes each lowercase and uppercase option individually.
Comment 6 commit-hook freebsd_committer 2019-01-04 02:49:36 UTC
A commit references this bug:

Author: allanjude
Date: Fri Jan  4 02:48:43 UTC 2019
New revision: 342754
URL: https://svnweb.freebsd.org/changeset/base/342754

Log:
  The lam(1) man page is unclear about the uppercase versions of the flags

  PR:		229571
  Submitted by:	Tim Chase <freebsd@tim.thechases.com>

Changes:
  head/usr.bin/lam/lam.1
Comment 7 Rodrigo Osorio freebsd_committer 2019-03-05 14:26:18 UTC
Can we mark this issue resolved ?
Comment 8 Tim Chase 2019-03-06 01:27:06 UTC
(In reply to Rodrigo Osorio from comment #7)

It looks like the patch is was accepted, so I have no objections to closing. Thanks!