Bug 1252161 - Various tweaks to "atomic" subcommand man pages
Various tweaks to "atomic" subcommand man pages
Status: CLOSED EOL
Product: Fedora
Classification: Fedora
Component: atomic (Show other bugs)
22
Unspecified Unspecified
unspecified Severity low
: ---
: ---
Assigned To: Daniel Walsh
Fedora Extras Quality Assurance
:
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2015-08-10 16:39 EDT by Robert P. J. Day
Modified: 2016-07-19 16:12 EDT (History)
3 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2016-07-19 16:12:21 EDT
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Robert P. J. Day 2015-08-10 16:39:33 EDT
"man atomic-host"

* subcommands listed under OPTIONS missing line breaks so all crunched together, also -r, --reboot options not mentioned in SYNOPSIS.

   "man atomic-info"

* SYNOPSIS should refer to both -h and --help as options, since --help is listed under OPTIONS. This inconsistency seems to occur in a number of "atomic" subcommand man pages.

   "man atomic-run"

       If the container image has a LABEL RUN instruction like the following:

       LABEL  RUN  /usr/bin/docker  run  -t  -i  --rm  \$OPT1   --cap-add=SYS_ADMIN   --net=host   -v   \$LOGDIR:/var/log   -v
       \$DATADIR:/var/lib --name \$NAME \$IMAGE \$OPT2 run.sh \$OPT3

but there's no "if" part after this ... it just goes on to the next sentence:

"If  this field does not exist ..."

  Also, that man page is confusing in terms of which command will be run. Early on, says that if LABEL RUN does not exist, "atomic run defaults to the following: /usr/bin/docker run -t -i --rm -v $LOGDIR:/var/log -v $DATADIR:/var/lib --name $NAME $IMAGE"

  But at the *bottom* of the "atomic-run" man page:

"The image will run with the following command:

       /usr/bin/docker  run  -t -i --rm --privileged -v /:/host -v /run:/run --net=host --ipc=host --pid=host -e HOST=/host -e
       NAME=$NAME -e IMAGE=$IMAGE --name $NAME $IMAGE"

So which is it?

   "man atomic-stop"

"If the container image has a LABEL STOP instruction like the following:

"CLABEL STOP /usr/bin/docker kill -s HUP --name $NAME $IMAGE
^ ??? "CLABEL"? Is that correct?

   "man atomic-uninstall"

"... if this field does not exists [sic]"

   "man atomic-update"

"atomic  update  will  pull  the  latest update of the image from the repository If ..."
          ^ Missing period.

"If a previously [sic] container based on this image exists, ..."

   "man atomic-upload"

"atomic upload will upload of [sic] the image to the repository"

   "man atomic-verify"

"If the tool finds a [sic] out of date image ..."

   "man atomic-version"

List of options missing line breaks, crunched together.
Also SYNOPSIS, "[-r], [--recurse]" should probably be just "[-r, --recurse]".
Comment 1 Robert P. J. Day 2015-08-11 02:51:36 EDT
As a general rule, the "atomic" subcommand man pages should be structured with an OPTIONS section followed by a separate COMMANDS section, the same way it's done with, say, "man docker."

For an example of this *not* being done, see "man atomic-host", where the OPTIONS section simply runs into talking about subcommands (unless that's simply a typo or formatting glitch).

I'll probably have one more set of notes on the atomic-related man pages shortly, then I'll leave it at that.
Comment 2 Robert P. J. Day 2015-08-11 03:43:01 EDT
Last set of notes on various "atomic" man pages.

   "man atomic-host"

SYNOPSIS
       atomic host status|upgrade|rollback  <-- should be bold, no?


   "man atomic-images"

  I'm intrigued that "atomic images" has a --prune option to delete dangling images, but "docker images" doesn't. Any reason for that?


   "man atomic-mount"

In OPTIONS section, seems like line breaks are missing after each option. That is, 

  -o|--options OPTIONS Specify options to be passed ...

should be rendered as:

  -o|--options OPTIONS
    Specify options to be passed ...


   "man atomic-uninstall"

In SYNOPSIS, "[-f][--force]" should be "[-f|--force]", no? Also, further down in OPTIONS section, "-f --force" should be "-f|--force". Or is it "-f,--force"? What's the standard?


   "man atomic-update"

As earlier:

   In SYNOPSIS, "[-f][--force]" -> "[-f|--force]"
   In OPTIONS, "-f --force" -> "-f,--force"         (or whatever)


   "man atomic-upload"

Same issue with "-p", "--pulp" as in previous note.


  I'm going to leave it at that.
Comment 3 Sally 2015-08-26 11:24:00 EDT
I think I covered them all!
Opened:
https://github.com/projectatomic/atomic/pull/131
Comment 4 Daniel Walsh 2015-08-27 07:51:13 EDT
Merged, thanks.
Comment 5 Robert P. J. Day 2015-08-27 08:20:58 EDT
In the update to docs/atomic-update.1.md, I see new line 10:

+[**-h**|**-h**]

That doesn't look right.
Comment 6 Sally 2015-08-27 13:32:19 EDT
(In reply to Robert P. J. Day from comment #5)
> In the update to docs/atomic-update.1.md, I see new line 10:
> 
> +[**-h**|**-h**]
> 
> That doesn't look right.

thanks :)  fixed it
Comment 7 Sally 2015-09-03 04:43:06 EDT
merged
Comment 9 Daniel Walsh 2015-09-03 07:36:01 EDT
Fixed in atomic-1.3
Comment 10 Daniel Walsh 2015-09-03 07:36:26 EDT
Lokesh can you build a new version of atomic for Fedora.
Comment 11 Fedora Admin XMLRPC Client 2016-06-08 10:19:21 EDT
This package has changed ownership in the Fedora Package Database.  Reassigning to the new owner of this component.
Comment 12 Fedora End Of Life 2016-07-19 16:12:21 EDT
Fedora 22 changed to end-of-life (EOL) status on 2016-07-19. Fedora 22 is
no longer maintained, which means that it will not receive any further
security or bug fix updates. As a result we are closing this bug.

If you can reproduce this bug against a currently maintained version of
Fedora please feel free to reopen this bug against that version. If you
are unable to reopen this bug, please file a new report against the
current release. If you experience problems, please add a comment to this
bug.

Thank you for reporting this bug and we are sorry it could not be fixed.

Note You need to log in before you can comment on or make changes to this bug.