-
Notifications
You must be signed in to change notification settings - Fork 2.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[CI:DOCS] Update podman.1.md, image-(diff, mount, exists) & images #10536
Conversation
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: infiniteregrets, rhatdan The full list of commands accepted by this bot can be found here. The pull request process is described here
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
Please after writing your markdown do a make docs and look at the man page.
The tables in the man page do not look good and we would need to work on go2man to fix these. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nice start @infiniteregrets !
Few questions:
|
I cannot find links for the mentioned pages in |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe take a look again at the updated version of the MANPAGE_SYNTAX. I am still updating it while going through the manpages. The latest PR should show you what changed.
|--------|-------------| | ||
| A | A file or directory was added. | | ||
| D | A file or directory was deleted. | | ||
| C | A file or directory was changed. | | ||
|
||
## OPTIONS | ||
|
||
#### **--format** |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should be **--format**=*format*
. Maybe adding a -f
option here would be also a good idea, but i believe you do not have to do this. But it is worth mentioning.
JSON
should be written in small letters, since it does not work when written in caps lock. So the old version was correct.
If no there is no input behind format the contents are simply listed below each other in the file. So it is not really true that json
is the only valid option.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The bold version after an eqaul sign should be used when there is a standard input. Since --format does not have this it should be italic.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'll fix that, can you confirm the JSON part? Because I still think acronyms should be in capitals
@@ -28,26 +33,31 @@ Mount all images. | |||
|
|||
#### **--format**=*format* | |||
|
|||
Print the mounted images in specified format (json). | |||
Print the mounted images in specified format (`JSON`). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
JSON
should also be small.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
From what I can see caps is correct.... https://www.rfc-editor.org/info/std90
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
$ podman image diff --format JSON alpine
Error: only supported value for '--format' is 'json'
$ podman image diff --format json alpine
<works>
Writing it in caps lock does not work as you can see. I think it has to be defined what is more important, that it is written in caps like an acronym is written or that the right input for the flag is listed. I think that the later variant is more important. You can still describe it in the description of the option as JSON
but if you list the argument for the flag in a table or refer to it should be small.
For the description should also be mentioned what happens if you don't right an input after the equal sign. JSON is the only xml like format that can be selected here, but if you just leave it blank the output is plain text.
Btw. I think that the flag does not even work. Input after the equal sign is simply ignored.
edit: spelling
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I agree, there is something buggy about this. And the examples use diff
when they should be using image diff
. I remember testing the command on my machine and thought I was doing something wrong. I am going test this command more and open an issue
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Only the lowercase version is accepted so we should not show this as JSON
Can you squash all of your commits. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
sorry for the tardy review, it's been a week! This is shaping up nicely, I left a few more comments.
Thanks for the suggestion! I didn't know about this. I am kinda new to this whole pull request thing and I am not sure if this is the right place to ask this but, after squashing a few commits I was trying to sign the ones I had not signed before so I found a solution on stackoverflow: |
@nalind do you have some git suggestions for @infiniteregrets ? Unfortunately you've gone into regions of git that I struggle with too. |
|
Thanks @nalind, looks like I was able to make it work somehow. Unfortunately the changes I made in other files which weren't pushed here are lost |
@TomSweeneyRedHat can you please confirm who compiled |
I believe it was me.
If you do It will show you the history of the source. If you go to the end, it will show you who created the file. |
@infiniteregrets Where does this one stand now? It looks like you've learned more about git than you anticipated! However, you have a white space issue somewhere that the CI doesn't like, a file that's missing, and we've one or two other PR's in flight for some of these files. Are you able to move this forward? |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
On the whole, this looks good. Some comments, please make sure options/arguments work when you change them (uppercase vs lowercase etc...)
The man pages are validated with two scripts: hack/xref-helpmsgs-manpages
and hack/man-page-checker
please make sure they pass. I think the extra newline after the headings causes the script to fail.
|
||
## OPTIONS | ||
|
||
#### **--format** | ||
#### **--format**, **-f**=*format* |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
-f
is not valid for image diff
$ podman image diff -f json alpine
Error: unknown shorthand flag: 'f' in -f
podman-image-diff - Inspect changes on an image's filesystem | ||
|
||
## SYNOPSIS | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think our validate script does not allow an extra newline after the heading.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It does work, but for the uniformity of all manpages I'll specify in the MANPAGE_SYNTAX, that there shouldn't be a new line.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@Procyhon I am using markdownlint, which is a vscode extension and they suggest using a new line https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md#md022
I think it just makes the markdown source code more readable
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
But let me know what is the final verdict on this
**podman image mount** [*options*] [*image* ...] | ||
|
||
**podman image mount** [*options*] name | ||
**podman mount** [*options*] name |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is not correct podman mount
is used for containers. This page is about podman image mount
.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[OUTDATED]
The synopsis was correct. The input of images after the command or the options is only required when the --all
option isn't used. And I believe that image is the better term here.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The synopsis was correct. The input of images after the command or the options is only required when the --all option isn't used. And I believe that image is the better term here.
I would revert this comment.
I added the following definition for cases like these into the MANPAGE_SYNTAX:
Many manpages include the OPTIONS --all, -a and/or --latest, -l. In this case there is no
container name
orID
needed after the initial command. Because most of the other OPTIONS still need thecontainer name
orID
, it is defined that the container argument in the command should not be put in brackets. It should also be noted in the IMPORTANT section in the DESCRIPTION of the OPTION.
I believe this is a good way to work with --all, -a and --latest, -l without compromising the command structure and keeping the general idea behind it intact.
|
||
Alter the output into a different format. The only valid format for diff is `json`. | ||
Alter the output into a different format. The only valid format for diff is `JSON`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
JSON should be lowercase. The uppercase one throws an error.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Where is the error coming from on JSON vs json? We need to stop that error, JSON is the correct capitalization.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It has to be fixed in containers/common https://github.com/containers/common/blob/6c933f226ed44491d082d6d52cbe31ae6fe0e76f/pkg/report/validate.go#L5 where it should be probably (json|JSON)
@@ -28,26 +33,31 @@ Mount all images. | |||
|
|||
#### **--format**=*format* | |||
|
|||
Print the mounted images in specified format (json). | |||
Print the mounted images in specified format (`JSON`). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Only the lowercase version is accepted so we should not show this as JSON
|
||
## EXAMPLE | ||
|
||
- Diff of two different python images. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
podman image diff will accept only one argument so the examples are wrong.
@Luap99 I was able to fix #10649 and add the functionality to find diff between two images. Although I am done with my work but when I run
Just feeling a bit overwhelmed looking at this? Any ideas on what I could be possibly doing wrong? I also changed the regular expression to accept Also, I am really sorry for not testing everything thoroughly. Next time I'll test as I go! Just had a hard time configuring my environment, finally switched to a fedora VM and everything works smoothly. Should I just open a pull request and ask for help there? |
Thanks @TomSweeneyRedHat, I will be able to move this forward once the image diff thing is fixed |
@infiniteregrets: PR needs rebase. Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. |
Can you compile with
Yes
I think it's good to accept both.
Don't worry, every beginning is difficult. Thanks for your work.
Yes, that would be good. |
@Luap99 |
@infiniteregrets, can you rebase? |
Hi, so I just tried to fix the podman.1.md page according to the https://github.com/containers/podman/edit/master/docs/MANPAGE_SYNTAX.md. I was able to do the same for some other pages as well, but before I push the changes I would like to know if this page is okay. I might have made some mistakes, so please do lmk! and I will fix them asap.
I have a few questions regarding the page:
--runtime-flag
on the version of podman I am using which is 2.0.6. Was this recently introduced?--remote
option I am not sure if there is a better way to write it, "Access Podman service will be remote".why is the word in "engine" in square brackets. what would be the correct way to put it? should i just highlight this with backticks?
Thank you so much! Please lmk if there is a better way to put things and if there any related webpages for the commands/options that could be helpful for someone.
Signed off by: Mehul Arora [email protected]